a2a-adapter

A2A Adapter

Make any AI agent an A2A Protocol server: a few lines of Python for your own agent, or one command for a local agent like Claude Code or Pi.

a2a-adapter wraps agent CLIs, local agents, workflow engines, and Python agent frameworks behind the A2A (Agent-to-Agent) Protocol. It handles AgentCard generation, JSON-RPC, task lifecycle, and streaming through the official A2A SDK, so your adapter only needs to invoke the underlying agent.

Works with Claude Code, Codex, Pi, OpenClaw, n8n, LangGraph, LangChain, CrewAI, Ollama, Hermes Agent, and custom Python functions.

Two Ways to Use It

Both need Python 3.11+ and serve the same A2A server, with an auto-generated Agent Card at /.well-known/agent-card.json.

1. Use It as an SDK

Add A2A support to your own agent code. Install a2a-adapter into your project's virtual environment, with extras for the framework you use:

pip install a2a-adapter              # core
pip install "a2a-adapter[langchain]" # or [crewai], [langgraph], [all]

Wrap your agent in an adapter and serve it:

from a2a_adapter import CallableAdapter, serve_agent

async def my_agent(inputs: dict) -> str:
    return f"Echo: {inputs['message']}"

adapter = CallableAdapter(func=my_agent, name="Echo Agent")
serve_agent(adapter, port=9000)

Your agent is now an A2A server at http://localhost:9000, with its Agent Card at http://localhost:9000/.well-known/agent-card.json. To mount it in an existing ASGI app instead, use to_a2a(adapter).

Supported SDK Adapters

2. Use It as a CLI

Start a classic local agent (Claude Code, Codex, Pi, or OpenClaw) as an A2A server with one command.

Install the CLI as an isolated tool, so the a2a-adapter command lands on your PATH:

uv tool install a2a-adapter    # or: pipx install a2a-adapter

Upgrade later with uv tool upgrade a2a-adapter. Avoid a system-wide pip install: macOS's built-in pip runs Python 3.9, which is too old, and Homebrew and many Linux distributions block it (PEP 668).

Make sure the agent works on its own. a2a-adapter wraps the agent you already have; it doesn't install it. For example, install Claude Code and run claude once to sign in. If the agent isn't on PATH, pass --executable /path/to/agent.

Start it from the project directory the agent should work in:

a2a-adapter claude --port 9010
a2a-adapter pi --port 9012
a2a-adapter codex --port 9011
a2a-adapter openclaw --port 9008

Options before -- configure the A2A server. Options after -- are passed to the underlying agent CLI:

a2a-adapter claude --port 9010 -- --model <model>
a2a-adapter pi --port 9012 -- --model <model> --thinking high
a2a-adapter codex --port 9011 -- --model <model> --sandbox workspace-write
a2a-adapter openclaw --port 9008 --agent-id main --thinking high

Pi source commands can be selected without a shell wrapper:

A2A_PI_COMMAND='npx tsx /path/to/pi/packages/coding-agent/src/cli.ts' \
  a2a-adapter pi --port 9012

Run a2a-adapter -help for the supported agents, or a2a-adapter <agent> -help for agent-specific usage. The adapter owns protocol and session flags such as Pi's --mode rpc and Codex's --json; those flags cannot be overridden after --.

Configuring the Agent

The adapter runs the agent non-interactively (for example claude -p or codex exec), so there's no agent UI to change settings in. You configure it the same way you would without the adapter, in two ways:

• The agent's own config files. The adapter runs the agent as you, in the --cwd folder, so it reads your usual setup: ~/.claude/settings.json, CLAUDE.md, and MCP servers for Claude Code; ~/.codex/config.toml and AGENTS.md for Codex; Pi's settings and installed extensions. Claude Code, Codex, and OpenClaw start a fresh process for each request, so changes apply to the next request. Pi keeps one process running, so restart the server after changing Pi's config.
• Native CLI flags after --. Use these for settings that should apply only to this server, such as a different model or sandbox mode.

Documentation

• Quick Start - end-to-end setup and testing guide
• Examples - runnable examples for each adapter
• Architecture - SDK delegation, request flow, and internals
• Changelog - release notes and migration history
• Contributing - development setup and contribution guide

Star History

License

Apache-2.0 - see LICENSE.

Built by HYBRO AI. Powered by the A2A Protocol.