a2a

type AgentRunner ¶

type AgentRunner interface {
	Run(ctx context.Context, req RunRequest, sink RunSink) RunResult
}

AgentRunner drives one conversation turn: it composes capabilities, runs the model/tool loop, emits usage events, streams incremental text via sink, and returns the terminal outcome. It is the seam between this A2A surface and the agent-orchestration layer (internal/agent); cancellation flows through ctx.

This interface is defined consumer-side so the orchestration package need not import this one; cmd/assistant adapts the concrete implementation to it.

type CardRequest ¶

type CardRequest struct {
	ProjectName string
}

CardRequest identifies one authenticated extended-agent-card lookup.

ProjectName arrives on the A2A wire as GetExtendedAgentCardRequest.Tenant. NOTE the overload: A2A defines "tenant" as the ID of the agent owner, and internal/tenant uses "tenant" for the milo project scoping an apiserver read. Here it is neither — it is the milo PROJECT the caller is asking about, because GetExtendedAgentCardRequest carries no other field and the project is what scopes every capability in this service. The middleware authorizes the same field it is read from, so the two cannot disagree.

type CompactRequest ¶

type CompactRequest struct {
	ProjectName string
	// ContextID is the A2A contextId == conversation id whose history is
	// being compacted.
	ContextID string
}

CompactRequest identifies one manual, user-triggered history compaction (the "/compact" command), as opposed to a RunRequest turn.

type Compactor ¶

type Compactor interface {
	Compact(ctx context.Context, req CompactRequest) error
}

Compactor is implemented by an AgentRunner that also supports manual history compaction. It is a separate, optional interface — not folded into AgentRunner — because not every runner needs to support it (fakes used in tests of the run path have no reason to).

type Executor ¶

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

Executor implements a2asrv.AgentExecutor: it translates one agent run into the A2A v1.0 event sequence (submitted → working → artifact(s) → terminal status). The library owns everything else — task store, SSE framing, the JSON-RPC dispatch. Protocol validation of the message shape happens in the library; assistant-specific validation (projectName, non-empty text) happens here and surfaces as ErrInvalidParams.

func NewExecutor(runner AgentRunner, logger *slog.Logger) *Executor

func (e *Executor) Cancel(_ context.Context, ec *a2asrv.ExecutorContext) iter.Seq2[a2a.Event, error]

func (e *Executor) Execute(ctx context.Context, ec *a2asrv.ExecutorContext) iter.Seq2[a2a.Event, error]

type Mention ¶

type Mention struct {
	Kind     string `json:"kind"`
	Name     string `json:"name"`
	APIGroup string `json:"apiGroup,omitempty"`
}

Mention is one resource the user referenced in their message. APIGroup is present when the client resolved it from API discovery and empty otherwise.

func Mentions(msg *a2a.Message, paramsMeta map[string]any) []Mention

type RunRequest ¶

type RunRequest struct {
	UserText    string
	ProjectName string
	// ContextID is the A2A contextId == conversation id == metering resource.
	ContextID string
	TaskID    string
	// Mentions are the resources the user pointed at with "@kind/name". They
	// are advisory context for the turn, already present verbatim in UserText.
	Mentions []Mention
}

RunRequest is one conversation turn to run for a task.

type RunResult ¶

type RunResult struct {
	State RunState
	// Text is the final assistant answer (accumulated across streamed deltas).
	Text string
	// Error is a human-readable failure message when State is [RunFailed].
	Error string
}

RunResult is the terminal outcome of AgentRunner.Run.

type RunSink ¶

type RunSink interface {
	// OnTextDelta is called for each chunk of generated assistant text.
	OnTextDelta(text string)
	// OnToolStart is called when the model asks for a tool (including the
	// built-in load_skill, which is how a skill load becomes visible).
	OnToolStart(act ToolActivity)
	// OnToolFinish is called once the call has run, with its outcome and
	// elapsed time.
	OnToolFinish(act ToolActivity)
}

RunSink receives incremental output while an agent run is in progress. The executor's sink implementation translates each delta into an A2A artifact event and each tool lifecycle callback into a working status update.

type RunState ¶

type RunState string

RunState is the terminal outcome of an agent run.

const (
	// RunCompleted means the agent produced a final answer.
	RunCompleted RunState = "completed"
	// RunFailed means the run errored.
	RunFailed RunState = "failed"
	// RunCanceled means the run was canceled (via context cancellation).
	RunCanceled RunState = "canceled"
)

type SkillAdvertiser ¶

type SkillAdvertiser interface {
	ProjectSkills(ctx context.Context, req CardRequest) ([]a2a.AgentSkill, error)
}

SkillAdvertiser is implemented by an AgentRunner that can describe what a project is entitled to. Optional, exactly like Compactor: a nil advertiser means the extended card is simply not offered.

type ToolActivity ¶

type ToolActivity struct {
	// ID correlates the started and finished halves of one call. Empty when
	// the provider assigned no tool-call id.
	ID string
	// Name is the model-facing tool name (a provider tool, or a built-in such
	// as load_skill).
	Name string
	// Summary is a short human-readable argument line, e.g. "project=demo".
	Summary string
	// OK reports success; meaningful on the finished half only.
	OK bool
	// Elapsed is how long the call took; meaningful on the finished half only.
	Elapsed time.Duration
}

ToolActivity is one tool invocation as the client should see it: enough to render an activity row, and nothing else. Summary is already redacted and capped by SummarizeToolInput — raw tool arguments never reach this struct, because everything in it is streamed to the client.