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

For the full runtime configuration matrix, outbound client settings, and deployment notes, see Usage Guide.

Operational Notes

When A2A_DATABASE_URL is unset and CODEX_WORKSPACE_ROOT is configured, the default SQLite database is created under ${CODEX_WORKSPACE_ROOT}/.codex-a2a/codex-a2a.db.

On startup, codex-a2a auto-creates its own runtime-state tables and applies versioned runtime-state schema migrations in place. This migration ownership currently covers only the adapter-managed a2a_* runtime-state tables and intentionally excludes the A2A SDK task-store schema.

YOLO-equivalent startup note:

• codex-a2a does not add a separate --yolo flag or YOLO environment variable.
• To start the underlying Codex process with YOLO-equivalent behavior, set:
  • CODEX_APPROVAL_POLICY=never
  • CODEX_SANDBOX_MODE=danger-full-access
• A2A_EXECUTION_* settings are discovery metadata only and do not change how the Codex subprocess starts.

Agent Card: http://127.0.0.1:8000/.well-known/agent-card.json

Authenticated extended card:

• JSON-RPC: agent/getAuthenticatedExtendedCard
• HTTP: GET /extendedAgentCard

Outbound peer auth is configured with A2A_CLIENT_BEARER_TOKEN or A2A_CLIENT_BASIC_AUTH; credentials are only sent to hosts listed in A2A_CLIENT_ALLOWED_HOSTS. The embedded a2a_call(...) tool also rejects private/loopback targets unless A2A_CLIENT_ALLOW_PRIVATE_HOSTS=true; see the Usage Guide for the complete client-side matrix.

When To Use It

Use this project when:

• you want to keep Codex as the runtime
• you need A2A transports and Agent Card discovery
• you want a maintained adapter/service contract instead of owning A2A transport, persistence, auth, and Codex-specific control mappings yourself
• you want inbound serving and outbound peer access in one deployable unit

Prefer a2a-client-hub when you need a broader application-facing integration layer or higher-level A2A consumption (see Ecosystem for details).

Look elsewhere if:

• you need hard multi-tenant isolation inside one shared runtime
• you want this project to manage your process supervisor or host bootstrap
• you want a general runtime-agnostic A2A server rather than a Codex adapter

Highlights

• A2A HTTP+JSON endpoints such as /message:send and /message:stream
• A2A JSON-RPC support on POST /
• Embedded client access through codex-a2a call
• Autonomous outbound peer calls through the a2a_call tool
• SSE streaming with normalized text, reasoning, and tool_call blocks
• Session continuity and session query extensions
• Interrupt lifecycle mapping and callback validation
• Transport selection, Agent Card discovery, timeout control, and bearer/basic auth for outbound A2A calls
• Payload logging controls, secret-handling guardrails, and released-CLI startup / source-based runtime paths

Boundaries

Portable vs Private Surface:

• Treat the core A2A send / stream / task methods plus Agent Card discovery as the portable baseline.
• Treat codex.* methods plus metadata.codex.directory and metadata.codex.execution as the Codex-specific control plane for Codex-aware clients.
• Treat one deployed instance as a single-tenant trust boundary, not a hardened multi-tenant runtime.

The normative compatibility split and deployment model live in Compatibility Guide and Security Policy.

Further Reading

• Usage Guide Runtime configuration, outbound access, transport usage, and client examples.
• Extension Specifications Stable extension URI/spec index plus public-vs-extended card disclosure rules.
• Architecture Guide System structure, boundaries, and request flow.
• Maintainer Architecture Guide Internal module structure, request call chains, and persistence touchpoints for contributors.
• Compatibility Guide Supported Python/runtime surface, extension stability, and ecosystem-facing compatibility expectations.
• Optional External TCK Experiment Manual, non-normative investigation guidance; it is not part of CI or compatibility claims.
• Security Policy Threat model, deployment caveats, and vulnerability disclosure guidance.

Ecosystem

codex-a2a is an independent integration built on public upstream projects. The links below distinguish normative upstreams from community projects; inclusion does not imply endorsement or verified interoperability.

Normative Upstreams

• A2A Protocol: The Linux Foundation open protocol implemented by this adapter at the declared A2A 1.0 line.
• a2aproject/a2a-python: The official Apache-2.0 Python SDK; this repository pins the a2a-sdk package to 1.1.2.
• openai/codex: The Apache-2.0 Codex CLI repository containing the local App Server used by this adapter. OpenAI's open-source component list identifies the IDE extension and Codex cloud as not open source. Desktop and web product behavior is also separate from this local runtime and outside this repository's compatibility claim.

Community Gateways and Hubs

• liujuanjuan1984/a2a-client-hub: An application-facing integration layer for consuming A2A services such as codex-a2a and providing higher-level normalization.
• jinyitao123/a2a-gateway: Operates at the protocol-bridging layer, sitting between agent platforms and the A2A/MCP ecosystem to handle discovery and routing.

Community Implementations and Runtimes

• Intelligent-Internet/opencode-a2a: A complementary Python runtime implementation that shares similar protocol patterns and output negotiation practices.
• MyPrototypeWhat/codex-a2a: A lightweight TypeScript Express middleware implementation. Ideal for developers looking for in-process SDK integration within a Node.js environment.

Development

For contributor workflow, validation, release handling, and helper scripts, see Contributing Guide and Scripts Reference. Use that workflow to create a PR from the working branch and merge into main after human review.

License

Apache License 2.0. See LICENSE.