These docs track the main branch and may describe unreleased features. The stable documentation lives at docs.docker.com.

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.

Early 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:tag

Flags

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: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

See 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

← Previous Coding Harnesses