# 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](https://a2a-protocol.org/latest/). This enables communication between Docker Agent and other agent frameworks that support A2A. > [!WARNING] > **Early support** > > A2A support is functional but still evolving. Tool calls, artifacts, and memory features have limited A2A integration. See limitations below. ## Usage ```bash # 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:tag ``` ## Flags | Flag | Default | Description | | --------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- | | `-l, --listen ` | `127.0.0.1:8082` | Address to listen on. | | `-a, --agent ` | (first agent) | Name of the agent to expose when the config contains multiple agents. Defaults to the team's first agent. | | `-s, --session-db ` | `/session.db` | Path to the SQLite session database. | | `--working-dir ` | current dir | Working directory the agent runs in. | | `--env-from-file ` | (none) | Load additional environment variables from a `.env` file (repeatable). | | `--models-gateway ` | (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 ` | (none) | Add a pre-tool-use hook (repeatable). See [Hooks](/ai/docker-agent/configuration/hooks/). | | `--hook-post-tool-use ` | (none) | Add a post-tool-use hook (repeatable). | | `--hook-session-start ` | (none) | Add a session-start hook (repeatable). | | `--hook-session-end ` | (none) | Add a session-end hook (repeatable). | | `--hook-on-user-input ` | (none) | Add an on-user-input hook (repeatable). | | `--hook-stop ` | (none) | Add a stop hook, fired when the model finishes responding (repeatable). | | `--auth-token ` | (none) | Bearer token required for agent-card and invocation requests. | | `--cors-origin ` | (none) | Allowed browser origins, comma-separated; empty disables CORS. | | `--insecure-no-auth` | `false` | Allow an unauthenticated non-loopback listener (unsafe). | | `--safety ` | `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 ` 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. ```bash $ docker agent serve a2a ./agent.yaml --auth-token "$A2A_TOKEN" \ --cors-origin http://localhost:3000 ``` ## Tool 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 > [!TIP] > **See also** > > For exposing agents via MCP instead, see [MCP Mode](/ai/docker-agent/features/mcp-mode/). For stdio-based integration, see [ACP](/ai/docker-agent/features/acp/). For the HTTP API, see [API Server](/ai/docker-agent/features/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