| name | a2a-protocol |
| description | Use this skill when the user asks about A2A (Agent-to-Agent) protocol communication, OASF record formats, AGNTCY directory operations, agent card parsing, or dirctl CLI usage. It provides comprehensive reference material for A2A integrations. |
A2A Protocol Skill
This skill provides knowledge about the A2A (Agent-to-Agent) protocol, the AGNTCY directory, and the OASF (Open Agent Standard Format) - everything needed to discover, connect to, and communicate with remote agents.
Recruited Agents
The /recruit command discovers agents from the AGNTCY directory and connects them to Claude Code. Two creation modes are available:
Skills (Recommended)
Skills create a /slash-command that the parent model executes directly. This is the most reliable way to proxy requests because the parent model runs the a2a-send command itself - no intermediary model to refuse.
Workflow:
/recruit <query> - discover agents, pick which to create, choose "skill" mode- Invoke with:
/<agent-name> <message> - e.g., /brazil-coffee-farm What is the current yield?
- Delete by removing the directory:
rm -rf .claude/skills/<agent-name>/
Skills are available immediately after creation - no restart needed.
Sub-Agents
Sub-agents create a .claude/agents/<name>.md file. Claude Code spawns a separate model to handle requests. This is useful when you want the sub-agent to have its own model (haiku/sonnet/opus) and reasoning, but note that sub-agent models may refuse to forward requests they deem outside the agent's advertised capabilities.
Workflow:
/recruit <query> - discover agents, pick which to create, choose "subagent" mode- Use them: "use the coffee-farm agent to check the yield" → Claude Code dispatches the sub-agent automatically
- Delete by removing the file:
rm .claude/agents/coffee-farm.md
Sub-agents require a restart to load - run /exit and relaunch claude.
Core Concepts
A2A Protocol
A2A (Agent-to-Agent) is a JSON-RPC 2.0 protocol for inter-agent communication over HTTP. This plugin uses v0.3.0+ (message/send method). Always check the protocolVersion in an agent's card to confirm compatibility.
OASF (Open Agent Standard Format)
OASF records are the standard format for describing agents in the AGNTCY directory. Each record contains metadata (name, description, skills, domains) and modules - including the integration/a2a module that holds the Agent Card.
AGNTCY Directory
A directory where agents register their OASF records. The dirctl CLI is the primary interface:
dirctl search - find agents by skill, name, domain, or module → returns CIDsdirctl pull <CID> - fetch the full OASF record for a CID
The directory server address is configured via DIRECTORY_CLIENT_SERVER_ADDRESS (default 0.0.0.0:8888).
Agent Card
The A2A Agent Card (found inside the integration/a2a module of an OASF record) describes an agent's communication interface: endpoint URL, supported protocol version, skills, capabilities, and transport options. It can also be fetched directly at <endpoint>/.well-known/agent.json.
Protocol
A2A uses JSON-RPC 2.0 over HTTP POST with the message/send method (v0.3.0+). Key format details:
- Messages require a
messageId field (UUID)
- Parts use
"kind": "text"
- Multi-turn uses
contextId in configuration
- Response:
result.kind: "message" with result.parts[]
Version Detection
curl -s <ENDPOINT_URL>/.well-known/agent.json
Check protocolVersion - must be "0.3.0" or higher.
Reference Files
For detailed information, see these reference files in the references/ directory:
| File | Contents |
|---|
oasf-structure.md | OASF record fields, Agent Card fields, HTTP endpoint resolution |
a2a-protocol-cheatsheet.md | Protocol version detection, method tables, curl templates, response formats |
error-handling.md | Timeouts, retry policy, structured error format |
dirctl-search.md | dirctl search and pull command examples |
