Architecture¶
The a2a CLI is a thin layer over the a2a-go SDK. The SDK owns the protocol: card parsing, interface selection, the JSON-RPC, REST and gRPC clients, and the event types. The CLI owns argument parsing, configuration, credentials, plugins, output and the process lifecycle. This page follows one command through the code and maps the packages. The rules for laying out new code are in the contributor note internal/DESIGN.md.
Life of a command¶
a2a send -a localhost:8080 "hi" goes through these steps.
- Build the command tree.
maincallscli.Execute, which builds the cobra tree innewRootCmd(internal/cli/root.go). Before it returns, it loads the configuration once, without--config, to readplugins-enabled. When that is true, it scansPATHand adds a command for each command plugin. See Command Plugins. - Parse flags. cobra parses the command line.
- Load configuration. The root
PersistentPreRunEruns before every command. It loads the configuration store again, now with--config(clicfg.Load), and callsclicfg.Bind, which fills each flag of the running command that the command line did not set. It prints a warning for each protected setting it ignored in a discovered.env. See Configuration Layers. - Prepare.
PersistentPreRunEthen routes HTTP through--unix-socketif set, sets up the credential helpers, checks--output, and builds the event handler chain. - Build the request.
sendturns the positional text and the part flags into ana2a.SendMessageRequest. - Create the client.
newAgentClient(internal/cli/client.go) loads--ca-cert, resolves the card and builds ana2aclient.Client. - Call the agent.
sendcallsSendMessage, orSendStreamingMessagewith--stream, and passes each event to the handler chain. - Exit. The deferred
destroyClientcloses the transport, which also stops a transport plugin process.Executeturns an error into a message and an exit code withclierr.Classify.
flowchart LR
A[newRootCmd] --> B[cobra parses flags]
B --> C[PersistentPreRunE<br/>clicfg.Load + Bind]
C --> D[RunE builds request]
D --> E[newAgentClient]
E --> F[SendMessage / stream]
F --> G[handler chain<br/>saver, printer]
F -. error .-> H[clierr.Classify<br/>exit code]
The client factory¶
newAgentClient takes exactly one of two inputs.
| Input | What happens |
|---|---|
--agent-card |
resolveCard fetches the card with the service parameters and credential helper headers attached. a2aclient.NewFromCard picks one of its interfaces, using --transport as the preferred order. |
--endpoint |
No card. --endpoint needs exactly one --transport, and a2aclient.NewFromEndpoints connects to that one interface. |
Both pass the factory options built in clientFactoryOpts:
- The SDK defaults are disabled and the CLI registers its own transports: REST, JSON-RPC and gRPC for protocol v1.0, and the same three through the
a2av0compatibility layer for v0.3.--a2a-version 1.0or--a2a-version 0.3registers only one set. - The REST and JSON-RPC transports share one
http.Clientwith no total timeout. The a2a-go default client caps each request at 3 minutes; the CLI leaves the limit to the--timeoutcontext. The client's transport is wrapped inutils.ActivityTransport, so response bytes reset the streaming inactivity timer. See Streaming and Timeouts. - gRPC uses TLS with the system roots, or the roots in
--ca-cert, or plaintext with--insecure, and dials through the socket with--unix-socket. - With credential helpers configured, a call interceptor adds their headers to every call. See Credential Helpers.
- Transport plugins add factories for the custom bindings the card lists. See Transport Plugins.
Cards often advertise a gRPC interface with an http:// or https:// URL, which grpc.NewClient cannot resolve. The CLI's gRPC factory strips the scheme and dials host:port. With --unix-socket it uses the passthrough resolver, since the socket dialer ignores the address. Discovery and Transports describes the selection in full.
Event handlers¶
Commands that receive events (send, chat, task get, task subscribe) pass each one to globalConfig.handleEvent, which runs the chain built in internal/cli/events.go:
- With
--save-fileparts, the file part saver (internal/fileparts) writes the raw file parts of the event to disk. - The printer (
internal/output) writes the event in the--outputformat.
chat appends a third handler that carries the context and task IDs from one turn to the next. A handler that fails stops the chain and fails the command.
Errors¶
Every failure ends as a clierr.Error with a code, a message, an optional hint and an exit status. Code that knows the category creates one directly: clierr.Usage for bad input and clierr.CardResolution for a failed card fetch. clierr.Classify sorts any other error: a deadline is a timeout, an a2a.Error from the agent is a protocol error, a network failure is an I/O error, and the rest are internal errors. Errors and Exit Codes lists the codes.
Packages¶
| Package | Responsibility |
|---|---|
internal/cli |
Cobra commands, one file per command; root setup, the client factory, credential wiring, event handlers |
internal/clicfg |
Configuration store over the environment, .env, YAML and JSON files; binding to flags; environment for transport plugins |
internal/clierr |
Error codes, exit statuses, classification, URL redaction |
internal/flagparse |
Flag value types: card reference, message parts, metadata, service parameters, transports, task states |
internal/output |
Text and JSON rendering of cards, tasks, messages, events and lists |
internal/polling |
Polling fallback for --stream, and task get --wait |
internal/chat |
The interactive session: turns, identifiers, interrupts |
internal/credhelper |
Credential helper protocol, scope selection, caching, the call interceptor |
internal/fileparts |
Writes raw file parts to the --save-fileparts directory |
internal/transportplugin |
Finds and launches a2a-transport-* plugins; the proxy transport |
internal/commandplugin |
Finds and runs a2a-* command plugins |
internal/cacert |
Loads the --ca-cert file |
internal/unixsocket |
HTTP transport and gRPC dialer for --unix-socket |
internal/utils |
Inactivity timeout and activity transport |
internal/clidoc, internal/tools/gendocs |
Generate the command reference |
devkit/cliplugin |
Public helpers for writing command plugins |
devkit/clitransport |
Public helpers for writing transport plugins: loopback server, handshake, token check |
skills |
The agent skill that a2a skill prints |
Design notes¶
- Configuration is loaded twice.
plugins-enableddecides which commands exist, so it must be known before cobra parses anything.--configis a flag, so the full load waits until flags are parsed. - The CLI registers its own transports. It needs one HTTP client for all of them, without the SDK's 3-minute cap and with activity tracking, and it needs the v0.3 transports alongside the v1.0 ones.
- Plugins are separate programs. New commands and bindings need no rebuild of the CLI, and a plugin can be written in any language.