A2A

A2A (Agent-to-Agent) lets you expose an agent as a standards-compliant HTTP server or connect remote A2A agents as tool providers for your LLM. A2A vs sub-agents: sub-agents are in-process Go agents registered at build time — they share the same deployment and runtime. A2A connects agents that run in separate services, possibly in different languages or owned by different teams. The integration boundary is an HTTP JSON-RPC call, not a Go function call. When you connect a remote A2A agent, the SDK fetches its agent card at NewAgent, discovers its published skills, and registers each skill as a tool named a2a_<server>_<skillId>. The LLM sees these tools identically to native tools and can invoke them in any run.

A2A server

Any agent can be exposed as an A2A HTTP server. Call RunA2A(ctx) after NewAgent — the server blocks until the context is cancelled, then shuts down gracefully. Endpoints:

Route	Purpose
`GET /.well-known/agent-card.json`	Agent card — name, description, skills, streaming capability, supported auth schemes
`POST /`	JSON-RPC v2 only — `SendMessage`, `SendStreamingMessage`, `GetTask`, etc.

The server accepts JSON-RPC v2 only (PascalCase methods: SendMessage, SendStreamingMessage, GetTask). Legacy slash-style method strings and HTTP REST paths are not supported.

a, err := agent.NewAgent(
    agent.WithName("my-agent"),
    agent.WithDescription("Helpful assistant exposed as an A2A server."),
    agent.WithLLMClient(llmClient),
    agent.WithA2ADefaultServer(),     // binds to localhost:9999, no auth
)
if err != nil {
    return err
}
defer a.Close()

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()

if err := a.RunA2A(ctx); err != nil {
    log.Fatal(err)
}

Custom server config

agent.WithA2AServer(&agent.A2AServerConfig{
    Hostname:     "0.0.0.0",
    Port:         8080,
    BearerTokens: []string{os.Getenv("A2A_SERVER_TOKEN")},
    AgentCard:    &interfaces.A2AAgentCard{ /* optional overrides */ },
})

Field	Default	Description
`Hostname`	`localhost`	Bind address — use `0.0.0.0` for external connections
`Port`	`9999`	TCP port
`BearerTokens`	empty (no auth)	Static pre-shared bearer tokens — enforced on every inbound call. The agent card endpoint stays public
`AgentCard`	auto-generated	Override card fields — merged with agent name, tools, and listen URL

Currently supported auth scheme: static bearer token. OAuth 2.0 / OIDC, API key, and mTLS are planned but not yet implemented.

See A2A Server example.

A2A client

Remote A2A agents connect as tool providers. The SDK resolves the agent card at NewAgent, discovers published skills, applies any SkillFilter, and registers each as a tool named a2a_<server>_<skillId>. Setup fails fast if a server is unreachable.

WithA2AConfig

import a2apkg "github.com/agenticenv/agent-sdk-go/pkg/a2a"

a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithA2AConfig(agent.A2AServers{
        "assistant": {
            URL:     "https://assistant.example.com",
            Timeout: 30 * time.Second,
        },
        "researcher": {
            URL:         "https://researcher.example.com",
            Token:       os.Getenv("A2A_TOKEN"),
            SkillFilter: a2apkg.A2ASkillFilter{AllowSkills: []string{"search", "summarize"}},
            Timeout:     60 * time.Second,
        },
    }),
)

WithA2AClients

import a2aclient "github.com/agenticenv/agent-sdk-go/pkg/a2a/client"

cl, err := a2aclient.NewClient("assistant", "https://assistant.example.com",
    a2aclient.WithTimeout(30*time.Second),
    a2aclient.WithToken(os.Getenv("A2A_TOKEN")),
)
if err != nil {
    return err
}

a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithA2AClients(cl),
)

SkipTLSVerify is available on client config for local HTTPS development only — avoid using it in production.

Runtime changes

Add or remove A2A agents after NewAgent via a.A2ARegistry() — skills are re-discovered on each run using the current registry state, with no restart required.

Examples

A2A Server

Inbound agent card and JSON-RPC

A2A Config

Outbound WithA2AConfig

A2A Client

Outbound WithA2AClients

Sub-agents

In-process specialist delegation

Approvals

A2A skills follow the same approval policy

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

A2A server

Custom server config

A2A client

WithA2AConfig

WithA2AClients

Runtime changes

Examples

A2A Server

A2A Config

A2A Client

Sub-agents

Approvals

​A2A server

​Custom server config

​A2A client

​WithA2AConfig

​WithA2AClients

​Runtime changes

​Examples

A2A Server

A2A Config

A2A Client

​Related

Sub-agents

Approvals

A2A server

Custom server config

A2A client

WithA2AConfig

WithA2AClients

Runtime changes

Examples

Related