Documentation
¶
Overview ¶
Package a2a provides an A2A (Agent-to-Agent) protocol adapter for LoopKit.
It consumes remote A2A agents as LoopKit tools:
- Agent-card discovery: GET /.well-known/agent.json → ToolDescriptor
- Execution: POST /a2a (message/send) + poll GET /a2a/tasks/{id} → ToolCalled
Replay semantics: AtMostOnce (default for remote side-effecting operations).
Long-running A2A tasks: blocked with context timeout (v1 limitation). See docs/concepts.md for the documented limitation on long-running tasks.
Usage:
adapter, err := a2a.NewAdapter("https://agent.example.com")
tools, err := adapter.Discover(ctx)
// tools is []runtime.ToolDescriptor — pass to loopkit.WithTools()
executor := a2a.NewExecutor("https://agent.example.com", adapter)
runner := loopkit.New(def,
loopkit.WithTools(executor),
...
)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type A2AMessage ¶
type A2AMessage struct {
// Role is always "user" for outgoing messages.
Role string `json:"role"`
// Parts carry the message content.
Parts []A2APart `json:"parts"`
}
A2AMessage is an A2A protocol message.
type A2APart ¶
type A2APart struct {
// Type is "text" or "data".
Type string `json:"type"`
// Text is the text content (when Type == "text").
Text string `json:"text,omitempty"`
// Data is the JSON data payload (when Type == "data").
Data json.RawMessage `json:"data,omitempty"`
}
A2APart is one content part of an A2A message.
type A2ARequest ¶
type A2ARequest struct {
// JSONRPC is always "2.0".
JSONRPC string `json:"jsonrpc"`
// Method is "message/send".
Method string `json:"method"`
// Params carries the message payload.
Params A2ARequestParams `json:"params"`
// ID is the JSON-RPC request ID.
ID string `json:"id"`
}
A2ARequest is the A2A protocol message/send request body.
type A2ARequestParams ¶
type A2ARequestParams struct {
// Message is the message to send to the agent.
Message A2AMessage `json:"message"`
}
A2ARequestParams is the params field of an A2A request.
type A2AResponse ¶
type A2AResponse struct {
JSONRPC string `json:"jsonrpc"`
Result json.RawMessage `json:"result,omitempty"`
Error *A2AError `json:"error,omitempty"`
ID string `json:"id"`
}
A2AResponse is the A2A protocol response envelope.
type A2ATask ¶
type A2ATask struct {
// ID is the task identifier.
ID string `json:"id"`
// Status is "pending", "working", "completed", "failed", "canceled".
Status string `json:"status"`
// Result is the task result (when Status == "completed").
Result json.RawMessage `json:"result,omitempty"`
// Error is the error message (when Status == "failed").
Error string `json:"error,omitempty"`
}
A2ATask is the status of an A2A task.
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter discovers and executes A2A agents as LoopKit tools. It is safe for concurrent use.
func NewAdapter ¶
func NewAdapter(baseURL string, opts ...AdapterOption) *Adapter
NewAdapter creates a new A2A Adapter for the agent at baseURL. baseURL is the base URL of the A2A agent (e.g. "https://agent.example.com").
func (*Adapter) Describe ¶
func (a *Adapter) Describe() []runtime.ToolDescriptor
Describe implements runtime.ToolExecutor.Describe. Returns descriptors based on the last discovered agent card. Call Discover first; returns empty slice if not yet discovered.
func (*Adapter) Discover ¶
Discover fetches the agent card and returns ToolDescriptors for each skill. If the agent has no skills, a single ToolDescriptor is returned for the agent itself. The card is cached; call Discover again to refresh.
func (*Adapter) Execute ¶
func (a *Adapter) Execute(ctx context.Context, call runtime.ToolRequest) (runtime.ToolResult, error)
Execute implements runtime.ToolExecutor.Execute. It sends a message/send A2A request and polls for the result.
Timeout limitation (v1): long-running tasks are blocked until ctx is cancelled. If the task takes longer than the context deadline, Execute returns an error. Future versions may map long tasks to AskHuman-style interruptions.
type AdapterOption ¶
type AdapterOption func(*Adapter)
AdapterOption configures an Adapter.
func WithHTTPClient ¶
func WithHTTPClient(c *http.Client) AdapterOption
WithHTTPClient sets a custom HTTP client.
func WithPollSettings ¶
func WithPollSettings(delay time.Duration, maxPolls int) AdapterOption
WithPollSettings configures task polling (delay between polls, max polls).
type AgentCard ¶
type AgentCard struct {
// Name is the agent's human-readable name.
Name string `json:"name"`
// Description explains what the agent does.
Description string `json:"description,omitempty"`
// URL is the base URL for A2A RPC calls.
URL string `json:"url"`
// Version is the agent's version string.
Version string `json:"version,omitempty"`
// Skills lists the agent's capabilities (mapped to ToolDescriptors).
Skills []AgentSkill `json:"skills,omitempty"`
}
AgentCard is the A2A agent card (/.well-known/agent.json). See: https://spec.a2aprotocol.ai/
type AgentSkill ¶
type AgentSkill struct {
// ID is the unique skill identifier.
ID string `json:"id"`
// Name is the human-readable skill name.
Name string `json:"name,omitempty"`
// Description explains what the skill does.
Description string `json:"description,omitempty"`
// InputSchema is the JSON Schema for the skill's input (optional).
InputSchema json.RawMessage `json:"inputSchema,omitempty"`
}
AgentSkill describes one skill (capability) offered by the agent.
type ErrAgentCardFetch ¶
ErrAgentCardFetch is returned when the agent card cannot be fetched.
func (*ErrAgentCardFetch) Error ¶
func (e *ErrAgentCardFetch) Error() string
type ErrMalformedCard ¶
ErrMalformedCard is returned when the agent card JSON is malformed.
func (*ErrMalformedCard) Error ¶
func (e *ErrMalformedCard) Error() string
func (*ErrMalformedCard) Unwrap ¶
func (e *ErrMalformedCard) Unwrap() error
Source Files