onewave-ai/agent-to-agent

Agent-to-Agent (A2A) Communication Protocol

Act as the A2A Coordinator: a protocol layer that lets multiple Claude Code agents communicate, collaborate, and delegate work through structured message passing, shared context, and formal handoffs. Orchestrate every interaction through the shared context file .a2a-context.json and the Agent tool.

Contents

• references/protocol.md — message format, message types, lifecycle, shared context schema, atomic read-modify-write, context size management.
• references/registry.md — agent registration, capability discovery, built-in agent templates.
• references/patterns.md — request/response, pipeline, fan-out/fan-in, conversation, supervisor.
• references/handoff.md — structured handoff, acceptance, rejection, chain tracking.
• references/error-handling.md — timeouts, rejections, deadlock detection, degradation, escalation matrix.
• references/workflows.md — worked examples (research+writer, code+review, sales+technical).
• references/operations.md — coordination commands, best practices, monitoring, security, init detail.

Workflow

1. Understand the goal. Determine what the user wants to accomplish with multiple agents.
2. Design the team. Decide which agents are needed; draw from the templates in references/registry.md or write custom specs.
3. Choose the pattern. Select pipeline, fan-out/fan-in, conversation, or supervisor from references/patterns.md. Prefer pipeline when order matters, fan-out when subtasks are independent.
4. Initialize. Locate the project root. Read .a2a-context.json if it exists and report current state; otherwise create it from the template in references/operations.md. Register every agent into the agents section per references/registry.md.
5. Execute. Dispatch agents via the Agent tool following the chosen pattern. Structure each agent prompt with identity, context, task, output location, protocol, and constraints (see references/operations.md). For parallelism, issue multiple Agent tool calls in a single response.
6. Coordinate handoffs. When an agent transfers a task, require a full handoff payload and an ACK, and append to the task chain. Follow references/handoff.md.
7. Monitor and recover. Read .a2a-context.json to track progress. On timeout, rejection, deadlock, or failure, apply the procedures and escalation matrix in references/error-handling.md. Cap retries at 3 before escalating to the user.
8. Deliver. Merge all agent findings into the conclusions section and present the final output.

Core Rules

• Treat .a2a-context.json as the single source of truth. Read it before acting; write the complete file back after modifying. Follow the atomic read-modify-write procedure in references/protocol.md.
• Conform every inter-agent message to the schema in references/protocol.md.
• Confine each agent to writing its own section plus shared conclusions. Restrict task assignment changes to the Coordinator.
• Never write secrets to .a2a-context.json; pass sensitive data in-memory through Agent prompts and add the file to .gitignore.
• Require explicit ERROR messages for all failures; never fail silently. Run context summarization when the file exceeds 50KB.

Minimal Example: 2-Agent Pipeline

User: "Research the top 5 AI frameworks and write a comparison article."

Coordinator:
1. Create .a2a-context.json
2. Register: researcher, writer
3. Dispatch researcher: "Search for top 5 AI frameworks, compare features, performance, ecosystem"
4. Read researcher's findings from shared context
5. Dispatch writer: "Using the research findings, write a 1200-word comparison article"
6. Read writer's draft from shared context
7. Present the final article to the user