codex-a2a

 ██████╗ ██████╗ ██████╗ ███████╗██╗  ██╗      █████╗ ██████╗  █████╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝╚██╗██╔╝     ██╔══██╗╚════██╗██╔══██╗
██║     ██║   ██║██║  ██║█████╗   ╚███╔╝█████╗███████║ █████╔╝███████║
██║     ██║   ██║██║  ██║██╔══╝   ██╔██╗╚════╝██╔══██║██╔═══╝ ██╔══██║
╚██████╗╚██████╔╝██████╔╝███████╗██╔╝ ██╗     ██║  ██║███████╗██║  ██║
 ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝     ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝

Expose Codex through A2A.

Repository: https://github.com/liujuanjuan1984/codex-a2a

Install: uv tool install --upgrade codex-a2a

Protocol: A2A 1.0 only.

Start the runtime explicitly with codex-a2a serve.

codex-a2a is an independent community adapter that adds an A2A service and control boundary to the local Codex CLI/App Server, with auth, streaming, session continuity, interrupt handling, and a built-in outbound A2A client. It is not an OpenAI or A2A Project distribution or endorsement.

What This Is

• An A2A adapter service for the local Codex runtime, with inbound runtime exposure plus outbound peer calling.
• It supports both roles in one process: serving as an A2A Server and hosting an embedded A2A Client for a2a_call and CLI-driven peer calls.

Architecture

flowchart TD
    External["A2A Clients / a2a-client-hub / Gateways"]

    subgraph Adapter["codex-a2a Runtime"]
        Ingress["Inbound A2A Surface\nHTTP+JSON + JSON-RPC"]
        Codex["Codex Runtime / Executor"]
        Outbound["Embedded A2A Client\nCLI call + a2a_call"]
    end

    subgraph Peers["Peer A2A Services"]
        PeerA2A["Peer A2A Agent"]
        PeerRuntime["Peer Runtime"]
        PeerA2A --> PeerRuntime
    end

    External -->|message/send,\nmessage:stream| Ingress
    Ingress -->|task execution| Codex
    Codex -->|stream events / tool results| Ingress
    Codex -->|a2a_call tool| Outbound
    Outbound -->|message/send,\nmessage:stream| PeerA2A
    PeerA2A -->|task / stream result| Outbound

For internal module boundaries and maintainer-facing request call chains, see Maintainer Architecture Guide.

Quick Start

Install the released CLI with uv tool:

uv tool install codex-a2a

Upgrade later with:

uv tool upgrade codex-a2a

Install an exact release with:

uv tool install "codex-a2a==<version>"

Before starting the runtime:

• Install and verify the local codex CLI itself.
• Configure Codex with a working provider/model setup and any required credentials.
• codex-a2a does not provision Codex providers, login state, or API keys for you.
• Startup fails fast if the local codex runtime is missing or cannot initialize.
• For long-running Linux service-manager deployments, set CODEX_CLI_BIN explicitly to the bundled native Codex binary. See Usage Guide for the recommended setup.

Self-start the released CLI against a workspace root:

DEMO_BEARER_TOKEN="$(python -c 'import secrets; print(secrets.token_hex(24))')"
A2A_STATIC_AUTH_CREDENTIALS='[{"id":"local-bearer","scheme":"bearer","token":"'"${DEMO_BEARER_TOKEN}"'","principal":"automation"}]' \
A2A_HOST=127.0.0.1 \
A2A_PORT=8000 \
A2A_PUBLIC_URL=http://127.0.0.1:8000 \
A2A_DATABASE_URL=sqlite+aiosqlite:////abs/path/to/workspace/.codex-a2a/codex-a2a.db \
CODEX_WORKSPACE_ROOT=/abs/path/to/workspace \
codex-a2a serve