workflow

type Agent ¶

type Agent interface {
	ID() string
	Card() AgentCard
	Strategy() Strategy
	Tools() []string
}

Agent describes identity and execution strategy for one logical agent.

func NewAgent(id string, strategy Strategy, opts ...AgentOption) Agent

type AgentCapabilities ¶

type AgentCapabilities struct {
	Streaming        bool `json:"streaming,omitempty"`
	PushNotification bool `json:"push_notification,omitempty"`
	StateTransition  bool `json:"state_transition,omitempty"`
}

AgentCapabilities declares optional runtime features.

type AgentCard ¶

type AgentCard struct {
	Name         string
	Description  string
	Skills       []Skill
	InputModes   []string
	OutputModes  []string
	Capabilities AgentCapabilities
}

AgentCard describes capabilities for discovery (e.g. A2A).

type AgentOption ¶

type AgentOption func(*simpleAgent)

AgentOption configures NewAgent.

func WithAgentDescription(desc string) AgentOption

func WithAgentTools(tools []string) AgentOption

type Artifact ¶

type Artifact struct {
	Name  string       `json:"name"`
	Parts []model.Part `json:"parts,omitempty"`
}

Artifact is a named bundle of parts produced during a run.

type BaseSession ¶

type BaseSession struct{}

BaseSession is a no-op MemorySession for tests or disabled memory.

func (BaseSession) Close(context.Context, error) error

func (BaseSession) Load(context.Context) ([]model.Message, error)

func (BaseSession) Save(context.Context, []model.Message) error

func (BaseSession) Vars(context.Context) (map[string]any, error)

type Board ¶

type Board struct {
	// contains filtered or unexported fields
}

Board is the graph execution blackboard: typed message channels plus control vars. Card-based kanban coordination lives in kanban.Board, not here.

Thread safety: public methods use a mutex (matches historical graph.Board behavior).

func NewBoard() *Board

func RestoreBoard(snap *BoardSnapshot) *Board

func (b *Board) AppendChannelMessage(name string, msg model.Message)

func (b *Board) AppendSliceVar(key string, value any) error

func (b *Board) Channel(name string) []model.Message

func (b *Board) ChannelsCopy() map[string][]model.Message

func (b *Board) GetVar(key string) (any, bool)

func (b *Board) GetVarString(key string) string

func (b *Board) RestoreFrom(snap *BoardSnapshot)

func (b *Board) SetChannel(name string, msgs []model.Message)

func (b *Board) SetVar(key string, value any)

func (b *Board) Snapshot() *BoardSnapshot

func (b *Board) UpdateSliceVarItem(key string, match func(any) bool, update func(any) any)

func (b *Board) Vars() map[string]any

type BoardSnapshot ¶

type BoardSnapshot struct {
	Vars     map[string]any             `json:"vars"`
	Channels map[string][]model.Message `json:"channels,omitempty"`
}

BoardSnapshot is a serializable representation of execution state (no kanban cards).

type Cloneable ¶

type Cloneable interface {
	Clone() any
}

Cloneable may be implemented by values stored in Board vars to provide a type-safe deep copy instead of the JSON fallback.

type ContextAssembler ¶ added in v0.1.1

type ContextAssembler interface {
	Assemble(ctx context.Context, req *Request) ([]model.Message, error)
}

ContextAssembler is an optional interface that a MemorySession may implement. When present, Runtime calls Assemble instead of Load to obtain history messages. This allows implementations to perform custom context assembly (e.g. RAG, summarization, sliding window) based on the current request.

The returned messages should NOT include req.Message; the runtime appends it.

type Dependencies ¶

type Dependencies struct {
	// contains filtered or unexported fields
}

Dependencies is a type-safe container for resources available to Strategy.Build. Each Strategy defines its own key constants and retrieves values via GetDep.

func NewDependencies() *Dependencies

func (d *Dependencies) Set(key string, val any)

type IncrementalSaver ¶ added in v0.1.1

type IncrementalSaver interface {
	Append(ctx context.Context, newMessages []model.Message) error
}

IncrementalSaver is an optional interface that a MemorySession may implement. When present, Runtime calls Append with only the newly produced messages instead of calling Save with the full message history.

type Memory ¶

type Memory interface {
	Session(ctx context.Context, contextID string) (MemorySession, error)
}

Memory provides per-agent session memory.

type MemoryFactory ¶

type MemoryFactory func(ctx context.Context, agent Agent) (Memory, error)

MemoryFactory creates a Memory for an agent.

type MemorySession ¶

type MemorySession interface {
	Load(ctx context.Context) ([]model.Message, error)
	Vars(ctx context.Context) (map[string]any, error)
	Save(ctx context.Context, messages []model.Message) error
	Close(ctx context.Context, runErr error) error
}

MemorySession is one Run's memory lifecycle (Load → Vars → Save → Close). All methods accept a context.Context to support timeout and cancellation for implementations backed by databases or network services.

type Request ¶

type Request struct {
	TaskID     string         `json:"task_id,omitempty"`
	ContextID  string         `json:"context_id,omitempty"`
	RuntimeID  string         `json:"runtime_id,omitempty"`
	RunID      string         `json:"run_id,omitempty"`
	Message    model.Message  `json:"message"`
	Inputs     map[string]any `json:"inputs,omitempty"`
	Config     *RequestConfig `json:"config,omitempty"`
	Extensions map[string]any `json:"extensions,omitempty"`
}

Request is one agent turn: user message plus optional inputs and metadata.

func NewTextRequest(text string) *Request

type RequestConfig ¶

type RequestConfig struct {
	AcceptedOutputModes []string `json:"accepted_output_modes,omitempty"`
}

RequestConfig holds optional request-level settings (A2A alignment, etc.).

type Result ¶

type Result struct {
	TaskID    string           `json:"task_id,omitempty"`
	Status    TaskStatus       `json:"status"`
	Messages  []model.Message  `json:"messages,omitempty"`
	Artifacts []Artifact       `json:"artifacts,omitempty"`
	Usage     model.TokenUsage `json:"usage"`
	State     map[string]any   `json:"state,omitempty"`
	Err       error            `json:"-"`
	LastBoard *Board           `json:"-"`
}

Result is returned by Runtime.Run after execution and finish logic.

func (r *Result) Text() string

type RunConfig ¶

type RunConfig struct {
	History        []model.Message
	Board          *Board
	StreamCallback StreamCallback
	MaxIterations  int
}

RunConfig holds resolved run-level settings. Exported so that Strategy implementations (e.g. flowgraph) can read stream callback, max iterations, etc.

func ApplyRunOpts(opts []RunOption) RunConfig

type RunOption ¶

type RunOption func(*RunConfig)

RunOption configures a single Run call.

func WithBoard(b *Board) RunOption

func WithHistory(msgs []model.Message) RunOption

func WithMaxIterations(n int) RunOption

func WithStreamCallback(cb StreamCallback) RunOption

type Runnable ¶

type Runnable interface {
	Execute(ctx context.Context, board *Board, req *Request, opts ...RunOption) (*Board, error)
}

Runnable is the compiled execution unit produced by Strategy.Build.

type Runtime ¶

type Runtime interface {
	Run(ctx context.Context, agent Agent, req *Request, opts ...RunOption) (*Result, error)
}

Runtime executes one agent Request using Strategy + optional Memory.

func NewRuntime(opts ...RuntimeOption) Runtime

type RuntimeOption ¶

type RuntimeOption func(*runtime)

RuntimeOption configures NewRuntime.

func WithDependencies(d *Dependencies) RuntimeOption

func WithMemoryFactory(f MemoryFactory) RuntimeOption

func WithPrepareBoard(fn func(ctx context.Context, agent Agent, req *Request, session MemorySession, opts []RunOption) (*Board, error)) RuntimeOption

type Skill ¶

type Skill struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

Skill is a lightweight skill declaration on an AgentCard.

type Strategy ¶

type Strategy interface {
	Kind() string
	Build(ctx context.Context, deps *Dependencies) (Runnable, error)
	Capabilities() StrategyCapabilities
}

Strategy describes how to execute one turn (graph, script, remote, …).

type StrategyCapabilities ¶

type StrategyCapabilities struct {
	AnswerKey string
}

StrategyCapabilities describes how Runtime reads outputs from the Board.

func (c StrategyCapabilities) AnswerVar() string

type StreamCallback ¶

type StreamCallback func(event StreamEvent)

StreamCallback receives streaming events during execution.

type StreamEvent ¶

type StreamEvent struct {
	Type    string `json:"type"`
	NodeID  string `json:"node_id"`
	Payload any    `json:"payload,omitempty"`
}

StreamEvent carries a streaming event emitted by a node during execution.

type Task ¶

type Task struct {
	ID        string     `json:"id"`
	Status    TaskStatus `json:"status"`
	CreatedAt time.Time  `json:"created_at"`
	Result    *Result    `json:"result,omitempty"`
}

Task represents a tracked unit of work managed by a TaskManager.

type TaskManager ¶

type TaskManager interface {
	GetTask(id string) (*Task, error)
	CancelTask(id string) error
	ListTasks() ([]*Task, error)
}

TaskManager is an optional capability for run/task orchestration (list/cancel). Default Runtime implementations may return a no-op or nil adapter.

type TaskStatus ¶

type TaskStatus string

TaskStatus is the terminal or intermediate status of a run.

const (
	StatusCompleted     TaskStatus = "completed"
	StatusWorking       TaskStatus = "working"
	StatusFailed        TaskStatus = "failed"
	StatusInputRequired TaskStatus = "input_required"
	StatusCanceled      TaskStatus = "canceled"
	StatusInterrupted   TaskStatus = "interrupted"
	StatusAborted       TaskStatus = "aborted"
)