A2A Protocol
Expose Docker Agent agents via Google's Agent-to-Agent (A2A) protocol for interoperability with other agent frameworks.
Overview
The docker agent serve a2a command starts an A2A server that exposes your agents using the A2A protocol. This enables communication between Docker Agent and other agent frameworks that support A2A.
WarningEarly support
A2A support is functional but still evolving. Tool calls, artifacts, and memory features have limited A2A integration. See limitations below.
Usage
# Start A2A server for an agent
$ docker agent serve a2a ./agent.yaml
# Specify a custom address
$ docker agent serve a2a ./agent.yaml --listen 127.0.0.1:9000
# Use an agent from an OCI registry
$ docker agent serve a2a myorg/agent:tagFlags
| Flag | Default | Description |
|---|---|---|
-l, --listen <addr> | 127.0.0.1:8082 | Address to listen on. |
-a, --agent <name> | (first agent) | Name of the agent to expose when the config contains multiple agents. Defaults to the team's first agent. |
-s, --session-db <path> | <data-dir>/session.db | Path to the SQLite session database. |
--working-dir <path> | current dir | Working directory the agent runs in. |
--env-from-file <file> | (none) | Load additional environment variables from a .env file (repeatable). |
--models-gateway <url> | (none) | Route all provider traffic through a models gateway URL. |
--code-mode-tools | false | Expose tools as a single "code" toolset that accepts a JavaScript snippet to run. |
--hook-pre-tool-use <cmd> | (none) | Add a pre-tool-use hook (repeatable). See Hooks. |
--hook-post-tool-use <cmd> | (none) | Add a post-tool-use hook (repeatable). |
--hook-session-start <cmd> | (none) | Add a session-start hook (repeatable). |
--hook-session-end <cmd> | (none) | Add a session-end hook (repeatable). |
--hook-on-user-input <cmd> | (none) | Add an on-user-input hook (repeatable). |
--hook-stop <cmd> | (none) | Add a stop hook, fired when the model finishes responding (repeatable). |
--auth-token <token> | (none) | Bearer token required for agent-card and invocation requests. |
--cors-origin <origins> | (none) | Allowed browser origins, comma-separated; empty disables CORS. |
--insecure-no-auth | false | Allow an unauthenticated non-loopback listener (unsafe). |
--safety <policy> | restricted | Tool safety policy; autonomous is permitted only through this explicit CLI flag. |
Authentication and network exposure
Loopback listeners may run without authentication. Non-loopback listeners require
--auth-token unless --insecure-no-auth explicitly acknowledges the exposure.
Clients must send Authorization: Bearer <token> for both agent-card discovery
and JSON-RPC invocation. Configure browser access with --cors-origin; it accepts
comma-separated literal origins or ~-prefixed regular expressions and permits
credentials only for matching origins.
$ docker agent serve a2a ./agent.yaml --auth-token "$A2A_TOKEN" \
--cors-origin http://localhost:3000Tool safety and migration
A2A sessions default to the restricted tool safety policy. Precedence is the
--safety flag, then agent YAML, then runtime YAML. YAML may select strict,
balanced, or restricted; safety: autonomous stops startup and directs the
operator to --safety autonomous. That CLI flag is the only deliberate opt-in
to autonomous tool execution.
Existing deployments should choose an explicit policy before upgrading. Migration
027 labels pre-existing sessions as run, so they cannot be resumed through
/invoke; clients must start new A2A contexts. An A2A context ID that collides
with another session is rejected without changing that session.
Downgrading to a binary that predates migration 027 fails because the session
database has a newer schema (ErrNewerDatabase). Restore an older database, or
use a binary that includes the migration. Revert changes without removing the
migration catalogue entry.
Features
- Auto port selection — Picks an available port if not specified
- Agent card — Provides standard A2A agent metadata
- Full Docker Agent features — Supports all tools, models, and gateway features
- Multiple sources — Load agents from files or OCI registries
TipSee also
For exposing agents via MCP instead, see MCP Mode. For stdio-based integration, see ACP. For the HTTP API, see API Server.
Current Limitations
- Tool calls are handled internally, not exposed as separate A2A events
- A2A artifact support not yet integrated
- A2A memory features not yet integrated
- Multi-agent (sub-agent) scenarios need further work
