Build a2a agents with Claude Code.
Run one command and your project ships a CLAUDE.md and a build-a2a-agent skill — so Claude Code opens already knowing the SDK. No docs to paste, no hallucinated APIs, no context burned reminding it how the platform works. Scaffold, build, and deploy a real agent in one flow.
$ a2a init research-agent+ research-agent/agent.py+ research-agent/a2a.yaml+ research-agent/AGENTS.md+ research-agent/CLAUDE.md+ research-agent/.claude/skills/build-a2a-agent/SKILL.md# open it in Claude Code — it already knows a2a$ claude› read CLAUDE.md → @AGENTS.md → build-a2a-agent skill› ready to add @a2a.tool skills, wire ctx.llm, deploy
From init to deployed, with Claude Code in the loop
Run a2a init
Scaffold the agent. The template writes AGENTS.md, a CLAUDE.md that imports it, and a .claude/skills/build-a2a-agent playbook alongside your starter agent.py.
Open in Claude Code
Claude Code loads CLAUDE.md → AGENTS.md automatically and can invoke the build skill. It already knows @a2a.tool, ctx.llm, workspace files, and the golden rules.
Run a2a deploy
Claude Code verifies with a2a validate and a2a card, then ships. You get a managed Postgres, an MCP server, an API, and a signed receipt per run.
Why teams build a2a agents in Claude Code
The reference lives in the repo, so the coding agent is productive on the first prompt instead of guessing your platform.
No context tax
You don't spend tokens or turns re-explaining the SDK. The scaffolded reference is the context, so Claude Code starts productive.
An invokable build playbook
The build-a2a-agent skill walks Claude Code through adding a @a2a.tool skill, wiring the LLM and workspace, and verifying before deploy.
Golden rules enforced
The reference states the non-negotiables — never read provider keys, use ctx.llm, write durable files through the workspace backend — so generated code is safe by default.
Verified before it ships
Claude Code runs a2a validate and a2a card as part of the loop, catching a broken agent before the platform build ever sees it.
“Your coding agent shouldn't have to guess your SDK. Ship the reference with the project.”
Before you deploy.
How does Claude Code know how to build an a2a agent?
When you run `a2a init`, the scaffold writes a CLAUDE.md that imports an AGENTS.md reference plus a .claude/skills/build-a2a-agent skill. Claude Code loads CLAUDE.md automatically, so it opens your project already knowing the SDK's golden rules, the @a2a.tool decorator, the RunContext API, and the deploy flow — no docs to paste in.
Do I have to paste in SDK docs or examples?
No. The reference ships inside the project. The AGENTS.md covers the agent anatomy, the four things you wire (LLM via ctx.llm, durable files, sandboxed execution, DeepAgents), auth, and the CLI workflow, and the build-a2a-agent skill is a step-by-step playbook Claude Code can invoke on demand. Your context window stays free for your actual code.
Does this stop Claude Code from hallucinating a2a APIs?
That's the point. Coding agents invent plausible-but-wrong APIs when they lack a source of truth. The shipped AGENTS.md is that source of truth — real decorator options, the ctx.llm credential rule (never read provider keys), the workspace-backed file paths — so Claude Code writes against the actual SDK, then verifies with `a2a validate` and `a2a card` before you deploy.
Which files does a2a init generate for Claude Code?
For the Python template you get AGENTS.md (the source-of-truth reference), a thin CLAUDE.md that imports it plus Claude-specific notes, and .claude/skills/build-a2a-agent/SKILL.md (an invokable build playbook) — alongside agent.py, a2a.yaml, requirements.txt, and README.md. The .claude directory is dev-only and is excluded from the deployed image.
Point Claude Code at a2a and let it build.
a2a init scaffolds a Claude-ready agent in one command — reference and build skill included — 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.