[psinghal20]

Summary

Adds src/agent_env/agents/AGENTS.md, a short guide to writing an A2A agent that agent-env can deploy, prompt, inspect and validate. It uses the Claude Code agent, agent-env's default and most tested agent, as the reference implementation, with pi only for the patterns Claude Code doesn't use (native trajectory, the snapshot changelog, custom peer tools), and points to the code rather than repeating it:

• Agent: a Docker image running an SDK-built A2A server, with the end of agents/claude-code/a2a_server.py and its entrypoint.sh as the whole entry point, and where the agent-level plumbing lives (model endpoint mapping, error bodies, lifespan, image, offline tests).
• Agent loop: handling tasks: the A2A methods agent-env calls (message/send, tasks/get, tasks/cancel), the task lifecycle the SDK owns, what run() receives and returns, errors, contexts and sessions, deadlines and cancellation, and streaming, each pointing to ClaudeCodeAgent.run, claude_bridge.py and their tests.
• Agent Card: identity and input_modes, what the SDK derives (RPC URL, streaming, the extensions list and agent-config's supported fields), and what updates it live, pinned by test_card_contract.py.
• Extensions: one section per urn:agentenv:* extension (agent-config, mcp-config, trajectory, skill-config, snapshot, peer-agents, triggers, attribution-probe, install, staging) and for custom extensions: what agent-env uses it for, what the SDK implements versus the agent, and the reference to copy, in Claude Code first, then pi, the protocol examples or its tests.
• The protocol: extensions.py as the wire-format source of truth, tasks/v1.py, transfers.py, the protocol README, and the deploy_agent / prompt_agent steps that show what agent-env sends an agent.
• Adding your own agent: ten steps from an empty bundle to a validated agent: copy agents/claude-code/, declare the agent, write the turn, map the model endpoint, add extensions, test offline, add agent.toml and a smoke task, agent-env run, a2a-agent put / validate, and use it from a task or as [agents] default_a2a_agent_id, with what validate doesn't cover.

It is about writing agents, not about changing the framework. Docs only; no code changes.

Test plan

• Every file and symbol the guide references exists on main.
• pytest tst/unit/agents tst/unit/bundle: 1040 passed.
• agent-env run agents --dry-run still plans both agents and both smoke tasks with the file in the bundle.
• Following steps 1, 7 and 8 (a copy of agents/claude-code/ as agents/my-agent/ in a new bundle, with a smoke task naming it by folder) plans with agent-env run <bundle> --dry-run.

🤖 Generated with Claude Code

Confidence Score: 5/5

The documentation change appears safe to merge.

Summary

Adds src/agent_env/agents/AGENTS.md, a guide to building, testing and registering an A2A agent.

• A new guide shows developers how to build an A2A agent for agent-env.

_{Reviews (6) · Last reviewed commit: "docs(agents): drop the reference-agent s..." · Reviewed by Greptile}