codex-a2a 0.6.2

Codex A2A runtime adapter

codex-a2a

Expose Codex through A2A.

codex-a2a adds an A2A runtime layer to the local Codex runtime, with auth, streaming, session continuity, interrupt handling, a built-in outbound A2A client, and a clear deployment boundary.

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.

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

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 /v1/card

Outbound peer auth is configured with A2A_CLIENT_BEARER_TOKEN or A2A_CLIENT_BASIC_AUTH; 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 thin service boundary instead of building your own adapter
• you want inbound serving and outbound peer access in one deployable unit

Prefer a2a-client-hub when:

• you need a broader application-facing client integration layer
• you want higher-level A2A consumption and upstream adapter normalization
• you want client-side integration concerns separated from the Codex runtime boundary

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 /v1/message:send and /v1/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.
• Security Policy Threat model, deployment caveats, and vulnerability disclosure guidance.

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.