Documentation
¶
Overview ¶
Package a2a provides Google A2A (Agent-to-Agent) protocol support for agent-sdk-go.
It enables cross-framework agent interoperability by implementing the A2A specification, allowing agents built with agent-sdk-go to communicate with agents built on any A2A-compliant framework (Google ADK, LangChain, CrewAI, etc.).
The package provides three main components:
Server: Exposes an agent-sdk-go agent as an A2A-compliant HTTP server, complete with agent card discovery, JSON-RPC message handling, and streaming support.
Client: Discovers and communicates with remote A2A agents, supporting both synchronous and streaming message patterns, multi-turn conversations, and task management.
RemoteAgentTool: Wraps a remote A2A agent as an interfaces.Tool, enabling seamless integration of remote agents into local agent tool chains.
Server usage:
card := a2a.NewCardBuilder("My Agent", "description", "http://localhost:9100/",
a2a.WithStreaming(true),
).Build()
srv := a2a.NewServer(agent, card,
a2a.WithAddress(":9100"),
a2a.WithMiddleware(authMiddleware),
)
srv.Start(ctx)
Client usage:
client, err := a2a.NewClient(ctx, "http://remote-agent:9100",
a2a.WithBearerToken("token"),
)
result, err := client.SendMessage(ctx, "hello",
a2a.WithContextID("conversation-1"),
)
Index ¶
- func ExtractResultText(result a2a.SendMessageResult) string
- type AgentAdapter
- type CardBuilder
- type CardOption
- type Client
- func (c *Client) CancelTask(ctx context.Context, taskID a2a.TaskID) (*a2a.Task, error)
- func (c *Client) Card() *a2a.AgentCard
- func (c *Client) Close()
- func (c *Client) GetTask(ctx context.Context, taskID a2a.TaskID) (*a2a.Task, error)
- func (c *Client) SendMessage(ctx context.Context, text string, opts ...SendOption) (a2a.SendMessageResult, error)
- func (c *Client) SendMessageStream(ctx context.Context, text string, opts ...SendOption) func(func(a2a.Event, error) bool)
- type ClientOption
- type RemoteAgentTool
- func (t *RemoteAgentTool) Description() string
- func (t *RemoteAgentTool) Execute(ctx context.Context, args string) (string, error)
- func (t *RemoteAgentTool) Name() string
- func (t *RemoteAgentTool) Parameters() map[string]interfaces.ParameterSpec
- func (t *RemoteAgentTool) Run(ctx context.Context, input string) (string, error)
- type RemoteAgentToolOption
- type SendOption
- type Server
- type ServerOption
- func WithAddress(addr string) ServerOption
- func WithBasePath(path string) ServerOption
- func WithIdleTimeout(d time.Duration) ServerOption
- func WithMiddleware(mw func(http.Handler) http.Handler) ServerOption
- func WithReadHeaderTimeout(d time.Duration) ServerOption
- func WithReadTimeout(d time.Duration) ServerOption
- func WithServerLogger(logger logging.Logger) ServerOption
- func WithShutdownTimeout(d time.Duration) ServerOption
- func WithWriteTimeout(d time.Duration) ServerOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractResultText ¶
func ExtractResultText(result a2a.SendMessageResult) string
ExtractResultText pulls text content from an A2A SendMessageResult. Non-text parts are converted with warnings logged via the provided logger.
Types ¶
type AgentAdapter ¶
type AgentAdapter interface {
Run(ctx context.Context, input string) (string, error)
RunStream(ctx context.Context, input string) (<-chan interfaces.AgentStreamEvent, error)
GetName() string
GetDescription() string
}
AgentAdapter is the interface that the A2A executor needs from an agent. It mirrors the subset of agent.Agent methods required for A2A.
type CardBuilder ¶
type CardBuilder struct {
// contains filtered or unexported fields
}
CardBuilder constructs an A2A AgentCard from agent-sdk-go Agent metadata.
func NewCardBuilder ¶
func NewCardBuilder(name, description, url string, opts ...CardOption) *CardBuilder
NewCardBuilder creates a new CardBuilder with required fields. It panics if name, description, or url is empty.
func (*CardBuilder) AddSkill ¶
func (b *CardBuilder) AddSkill(skill a2a.AgentSkill) *CardBuilder
AddSkill adds an explicit skill to the card.
func (*CardBuilder) Build ¶
func (b *CardBuilder) Build() *a2a.AgentCard
Build constructs the AgentCard.
func (*CardBuilder) SetTools ¶
func (b *CardBuilder) SetTools(tools []interfaces.Tool) *CardBuilder
SetTools sets the agent's tools, which will be converted to skills on Build().
type CardOption ¶
type CardOption func(*CardBuilder)
CardOption configures an AgentCard builder.
func WithDocumentationURL ¶
func WithDocumentationURL(url string) CardOption
WithDocumentationURL sets the documentation URL on the card.
func WithInputModes ¶
func WithInputModes(modes ...string) CardOption
WithInputModes sets the default accepted input MIME types.
func WithOutputModes ¶
func WithOutputModes(modes ...string) CardOption
WithOutputModes sets the default accepted output MIME types.
func WithProviderInfo ¶
func WithProviderInfo(org, url string) CardOption
WithProviderInfo sets the provider organization info on the card.
func WithStreaming ¶
func WithStreaming(enabled bool) CardOption
WithStreaming enables or disables streaming capability on the card.
func WithVersion ¶
func WithVersion(version string) CardOption
WithVersion sets the agent version on the card.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client discovers and communicates with remote A2A-compliant agents.
func NewClient ¶
NewClient creates a new A2A client that connects to the agent at the given URL. It resolves the agent card from /.well-known/agent-card.json automatically.
func NewClientFromCard ¶
func NewClientFromCard(ctx context.Context, card *a2a.AgentCard, opts ...ClientOption) (*Client, error)
NewClientFromCard creates a new A2A client from an already-resolved agent card.
func (*Client) CancelTask ¶
CancelTask cancels a running task.
func (*Client) Close ¶
func (c *Client) Close()
Close releases resources held by the client. It closes idle connections on the underlying HTTP transport. Safe to call multiple times.
func (*Client) SendMessage ¶
func (c *Client) SendMessage(ctx context.Context, text string, opts ...SendOption) (a2a.SendMessageResult, error)
SendMessage sends a synchronous message and returns the result.
type ClientOption ¶
type ClientOption func(*Client)
ClientOption configures an A2A client.
func WithBearerToken ¶
func WithBearerToken(token string) ClientOption
WithBearerToken sets a static bearer token for authentication on the A2A client. The token is injected into every outgoing request as an Authorization header.
func WithClientLogger ¶
func WithClientLogger(logger logging.Logger) ClientOption
WithClientLogger sets a logger for the A2A client.
func WithTimeout ¶
func WithTimeout(d time.Duration) ClientOption
WithTimeout sets the HTTP client timeout for the A2A client.
type RemoteAgentTool ¶
type RemoteAgentTool struct {
// contains filtered or unexported fields
}
RemoteAgentTool wraps an A2A client as an interfaces.Tool so that a remote A2A agent can be used as a tool by agent-sdk-go agents.
func NewRemoteAgentTool ¶
func NewRemoteAgentTool(client *Client, opts ...RemoteAgentToolOption) *RemoteAgentTool
NewRemoteAgentTool creates a tool from an A2A client.
func (*RemoteAgentTool) Description ¶
func (t *RemoteAgentTool) Description() string
func (*RemoteAgentTool) Name ¶
func (t *RemoteAgentTool) Name() string
func (*RemoteAgentTool) Parameters ¶
func (t *RemoteAgentTool) Parameters() map[string]interfaces.ParameterSpec
type RemoteAgentToolOption ¶
type RemoteAgentToolOption func(*RemoteAgentTool)
RemoteAgentToolOption configures a RemoteAgentTool.
func WithToolName ¶
func WithToolName(name string) RemoteAgentToolOption
WithToolName overrides the auto-generated tool name. Use this to prevent name collisions when registering multiple remote agents.
type SendOption ¶
type SendOption func(*sendConfig)
SendOption configures individual SendMessage / SendMessageStream calls.
func WithContextID ¶
func WithContextID(id string) SendOption
WithContextID sets the context ID for multi-turn conversations. Messages sharing a context ID are grouped into the same interaction thread.
func WithTaskID ¶
func WithTaskID(id a2a.TaskID) SendOption
WithTaskID continues an existing task by referencing its ID.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server wraps an agent-sdk-go agent and exposes it as an A2A-compliant HTTP server.
func NewServer ¶
func NewServer(agent AgentAdapter, agentCard *a2a.AgentCard, opts ...ServerOption) *Server
NewServer creates a new A2A server that serves the given agent. The agentCard describes the agent's capabilities to A2A clients. It panics if agent or agentCard is nil.
func (*Server) Addr ¶
Addr returns the resolved listen address after Start has been called. Before Start, it returns the configured address.
type ServerOption ¶
type ServerOption func(*Server)
ServerOption configures an A2A server.
func WithAddress ¶
func WithAddress(addr string) ServerOption
WithAddress sets the listen address for the A2A server.
func WithBasePath ¶
func WithBasePath(path string) ServerOption
WithBasePath sets the JSON-RPC endpoint base path. Defaults to "/".
func WithIdleTimeout ¶
func WithIdleTimeout(d time.Duration) ServerOption
WithIdleTimeout sets the maximum amount of time to wait for the next request when keep-alives are enabled. A zero value means no timeout.
func WithMiddleware ¶
func WithMiddleware(mw func(http.Handler) http.Handler) ServerOption
WithMiddleware adds an HTTP middleware to the A2A server. Middleware is applied in the order provided, wrapping the base handler. Use this for authentication, rate limiting, CORS, logging, etc.
func WithReadHeaderTimeout ¶
func WithReadHeaderTimeout(d time.Duration) ServerOption
WithReadHeaderTimeout sets the amount of time the server allows for reading request headers. Defaults to 10 seconds.
func WithReadTimeout ¶
func WithReadTimeout(d time.Duration) ServerOption
WithReadTimeout sets the maximum duration for reading the entire request, including the body. A zero value means no timeout.
func WithServerLogger ¶
func WithServerLogger(logger logging.Logger) ServerOption
WithServerLogger sets a logger for the A2A server.
func WithShutdownTimeout ¶
func WithShutdownTimeout(d time.Duration) ServerOption
WithShutdownTimeout sets the graceful shutdown timeout for the A2A server. Defaults to 30 seconds.
func WithWriteTimeout ¶
func WithWriteTimeout(d time.Duration) ServerOption
WithWriteTimeout sets the maximum duration before timing out writes of the response. A zero value means no timeout.
Source Files