a2a

type AgentCard ¶

type AgentCard struct {
	Name         string   `json:"name"`
	Description  string   `json:"description"`
	Version      string   `json:"version"`
	Capabilities []string `json:"capabilities"`
	InputSchema  any      `json:"input_schema,omitempty"`
	OutputSchema any      `json:"output_schema,omitempty"`
}

AgentCard describes an A2A agent's capabilities.

func CardFromSkills(name, description, version string, reg *skill.Registry) AgentCard

type Client ¶

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

Client connects to an external A2A agent.

func NewClient(baseURL string) *Client

func (c *Client) CreateTask(ctx context.Context, input string, metadata map[string]any) (*Task, error)

func (c *Client) GetAgentCard(ctx context.Context) (*AgentCard, error)

func (c *Client) GetTask(ctx context.Context, taskID string) (*Task, error)

func (c *Client) StreamTask(ctx context.Context, taskID string) (snapshots <-chan Task, errc <-chan error)

func (c *Client) WaitForCompletion(ctx context.Context, taskID string, pollInterval time.Duration) (*Task, error)

type DurableStore ¶ added in v0.10.0

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

DurableStore is a TaskStore backed by the durable queue (engine/queue) for restart-resumable scheduling and by checkpoint storage (storage.Storage) for the task record. Execution is driven by a queue.Worker wired to Executor, so a task whose worker dies is re-leased and resumed once its lease expires (orphan recovery), and tasks survive a process restart. The task record is a single checkpoint keyed by the task id (overwritten on each transition), which inherits storage's per-tenant scoping: a Get for another tenant's task resolves to ErrTaskNotFound.

func NewDurableStore(q *queue.Queue, store storage.Storage, handler Handler) *DurableStore

ds := a2a.NewDurableStore(q, store, handler)
w, _ := queue.NewWorker(q, ds.Executor, queue.WorkerConfig{ID: "a2a-worker-1"})
go w.Run(ctx)
srv := a2a.NewServerWithStore(card, ds)

func (d *DurableStore) Cancel(ctx context.Context, id string) (*Task, error)

func (d *DurableStore) Executor(ctx context.Context, run *queue.Run) queue.Result

func (d *DurableStore) Get(ctx context.Context, id string) (*Task, error)

func (d *DurableStore) Submit(ctx context.Context, input string, metadata map[string]any) (*Task, error)

type Handler ¶

type Handler func(ctx context.Context, task *Task) error

Handler processes A2A tasks. It should be idempotent: on the durable backend a task may be executed more than once (queue retries and orphan recovery are at-least-once), and re-running simply overwrites the task's output.

type RemoteToolOption ¶ added in v0.10.0

type RemoteToolOption func(*remoteToolConfig)

RemoteToolOption configures a remote-agent tool.

func WithPermission(p tool.Permission) RemoteToolOption

func WithPollInterval(d time.Duration) RemoteToolOption

type Server ¶

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

Server exposes an agent as an A2A endpoint. Task lifecycle is delegated to a TaskStore, so the same HTTP surface serves both the in-memory default and the durable, restart-resumable queue backend (see NewDurableStore).

func NewServer(card AgentCard, handler Handler) *Server

func NewServerWithStore(card AgentCard, store TaskStore) *Server

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Task ¶

type Task struct {
	ID        string         `json:"id"`
	Status    TaskStatus     `json:"status"`
	Input     string         `json:"input"`
	Output    string         `json:"output,omitempty"`
	Error     string         `json:"error,omitempty"`
	Metadata  map[string]any `json:"metadata,omitempty"`
	CreatedAt time.Time      `json:"created_at"`
	UpdatedAt time.Time      `json:"updated_at"`
}

Task represents an A2A task.

type TaskStatus ¶

type TaskStatus string

TaskStatus represents the status of an A2A task.

const (
	TaskStatusPending   TaskStatus = "pending"
	TaskStatusRunning   TaskStatus = "running"
	TaskStatusCompleted TaskStatus = "completed"
	TaskStatusFailed    TaskStatus = "failed"
	TaskStatusCancelled TaskStatus = "cancelled" //nolint:misspell // wire value; external clients may expect British spelling
)

type TaskStore ¶ added in v0.10.0

type TaskStore interface {
	// Submit persists a new task and begins (or schedules) its execution,
	// returning a snapshot of the created task.
	Submit(ctx context.Context, input string, metadata map[string]any) (*Task, error)
	// Get returns a snapshot of the task, or ErrTaskNotFound.
	Get(ctx context.Context, id string) (*Task, error)
	// Cancel transitions a pending or running task to the canceled state and
	// returns a snapshot. Terminal tasks are returned unchanged.
	//
	// Backends differ in whether Cancel preempts in-flight work: the in-memory
	// store aborts the handler via context cancellation; the durable store records
	// the cancellation and discards the handler's result when it finishes, but does
	// not interrupt a running handler.
	Cancel(ctx context.Context, id string) (*Task, error)
}

TaskStore persists A2A tasks and drives their execution. The Server delegates every task-lifecycle operation to a TaskStore so the backend — the in-memory default or the durable, restart-resumable queue (see NewDurableStore) — is swappable without touching the HTTP layer.

Implementations must be safe for concurrent use and honor the context tenant (see storage.WithTenant): a Get/Cancel for a task created under another tenant must return ErrTaskNotFound.