Build a2a agents with Codex.
a2a init writes an AGENTS.md — Codex's native instruction file — straight into your project. Codex opens already fluent in the SDK: the @a2a.tool decorator, ctx.llm, durable files, the deploy flow. No pasting docs, no invented APIs, just working code against the real platform.
$ a2a init invoice-agent+ invoice-agent/agent.py+ invoice-agent/a2a.yaml+ invoice-agent/AGENTS.md# AGENTS.md is Codex's native instruction file$ codex› reads AGENTS.md → knows @a2a.tool, ctx.llm, deploy flow› scaffolds a new skill against the real SDK
From init to deployed, with Codex in the loop
Run a2a init
Scaffold the agent. The template writes AGENTS.md — the file Codex reads as its instructions — plus your starter agent.py and manifest.
Open in Codex
Codex loads AGENTS.md automatically and knows the SDK: how to add a @a2a.tool skill, wire ctx.llm, and use the workspace-backed file paths.
Run a2a deploy
After Codex verifies with a2a validate and a2a card, ship it. You get a managed Postgres, an MCP server, an API, and a signed receipt per run.
Why teams build a2a agents in Codex
The instruction file ships in the repo, so Codex is productive on the first prompt and every teammate's tool reads the same reference.
Codex's native file, written for you
AGENTS.md is exactly what Codex looks for. You don't configure anything — a2a init drops the reference where Codex already reads.
One reference, every coding agent
AGENTS.md is the source of truth; CLAUDE.md and the .claude skill defer to it. Codex, Claude Code, and Cursor never drift apart.
Safe-by-default code
The golden rules are in the reference — use ctx.llm, never read provider keys, write durable files through the workspace backend — so generated skills follow platform policy.
Verified before it ships
Codex runs a2a validate and a2a card in the loop, so a broken agent is caught before the platform build touches it.
“One AGENTS.md, and every coding agent on your team speaks a2a fluently.”
Before you deploy.
How does Codex know how to build on a2a?
OpenAI Codex reads an AGENTS.md file at the repo root as its instruction source. `a2a init` writes exactly that file — a full SDK reference covering the @a2a.tool decorator, the RunContext API, the ctx.llm credential rule, durable file paths, and the CLI workflow — so Codex opens your project already fluent in the platform.
Why AGENTS.md specifically?
AGENTS.md is the emerging cross-tool standard for giving coding agents project instructions, and it's Codex's native file. a2a treats it as the single source of truth: the scaffolded CLAUDE.md and .claude build skill both defer to AGENTS.md, so Codex, Claude Code, and Cursor all read the same reference and can't drift apart.
Will Codex write against the real SDK or invent APIs?
Against the real SDK. The AGENTS.md ships the actual decorator options, the RunContext surface, and the golden rules — including never reading provider keys and always using ctx.llm — so Codex has a source of truth instead of guessing. It then verifies with `a2a validate` and `a2a card` before you deploy.
Does this work outside Codex?
Yes. AGENTS.md is tool-agnostic — Codex, Cursor, and other agents that honor it read the same file, and Claude Code gets a CLAUDE.md that imports it. One reference, every coding agent, so your whole team is productive regardless of which tool they use.
Give Codex the instructions and let it build.
a2a init scaffolds an agent with a Codex-native AGENTS.md in one command, and a2a deploy ships it with a managed Postgres database, an MCP server, an API, a frontend, and an Ed25519-signed receipt for every run. The whole agent app, built with the coding agent you already use.