a2a-protocol

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:

1. /recruit <query> — discover agents, pick which to create, choose "skill" mode
2. Invoke with: /<agent-name> <message> — e.g., /brazil-coffee-farm What is the current yield?
3. 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:

1. /recruit <query> — discover agents, pick which to create, choose "subagent" mode
2. Use them: "use the coffee-farm agent to check the yield" → Claude Code dispatches the sub-agent automatically
3. 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 CIDs
• dirctl 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