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

Error Handling

Recovery procedures for timeouts, rejections, deadlocks, and failures.

Agent Timeout

If an agent does not produce a result within the expected timeframe:

1. The Agent tool has its own timeout (Claude Code manages this)
2. If the spawned agent times out, the coordinator receives an error
3. Recovery procedure:
   a. Log the timeout in .a2a-context.json message_log
   b. Read any partial results the agent may have written to shared context
   c. OPTION A: Retry the same agent with a simplified task
   d. OPTION B: Route to a different agent
   e. OPTION C: Break the task into smaller pieces
4. Maximum 3 retries per task before escalating to the user

Task Rejection

An agent may decline a task if it lacks the required capabilities:

{
  "type": "ERROR",
  "payload": {
    "action": "TASK_REJECTED",
    "data": {
      "reason": "I don't have access to the WebSearch tool needed for this task",
      "required_capabilities": ["web_search"],
      "my_capabilities": ["code_generation", "debugging"],
      "suggested_agent": "researcher"
    }
  }
}

Coordinator response to rejection: 1. Log the rejection. 2. Query the registry for an agent with the missing capabilities. 3. Reroute the task. 4. If no suitable agent exists, report to the user.

Deadlock Detection

Deadlock occurs when two or more agents are waiting on each other.

Detection algorithm:

1. Read all tasks in .a2a-context.json
2. Build a dependency graph:
   - For each task with status IN_PROGRESS, check if it's blocked waiting for another task
   - For each BLOCKED task, check what it's waiting for
3. Detect cycles in the dependency graph
4. If cycle found:
   a. Log the deadlock with involved agents and tasks
   b. BREAK the cycle by:
      - Picking the lowest-priority task in the cycle
      - Cancelling it and informing its agent
      - The cancelled agent writes partial results and releases
   c. Notify the coordinator for re-planning

Deadlock prevention rules:

• Never let an agent wait on a response from an agent that is waiting on it.
• Give all QUERY messages a TTL; if no response by TTL, proceed without it.
• Have the Coordinator review the task dependency graph before dispatching.

Graceful Degradation

When an agent fails entirely:

1. Log the failure with error details
2. Save any partial results from the failed agent's context section
3. Assess impact:
   a. Was this a critical-path task? (blocks other tasks)
   b. Was this a parallel task? (other agents can compensate)
4. Recovery options:
   a. RETRY: Spawn a new instance of the same agent type
   b. REROUTE: Assign to a different agent with overlapping capabilities
   c. SIMPLIFY: Reduce task scope and retry
   d. ESCALATE: Inform the user that this subtask could not be completed
   e. SKIP: Mark as skipped and proceed (for non-critical tasks)
5. Update .a2a-context.json with the recovery action taken

Error Escalation Matrix

Handoff Protocol

Defines structured task handoff, acceptance, rejection, and chain tracking.

Structured Handoff Message

When transferring ownership of a task, include the full handoff payload:

{
  "type": "HANDOFF",
  "payload": {
    "action": "TRANSFER_TASK",
    "data": {
      "task": "Clear description of what needs to be done",
      "context_so_far": "Summary of all work completed, decisions made, and current state",
      "what_ive_tried": [
        "Approach 1: [description] -- Result: [outcome]",
        "Approach 2: [description] -- Result: [outcome]"
      ],
      "what_you_should_do": [
        "Specific next step 1",
        "Specific next step 2"
      ],
      "success_criteria": [
        "The output should include X",
        "Performance must meet Y threshold",
        "All tests must pass"
      ],
      "files_modified": [
        "/path/to/file1.ts",
        "/path/to/file2.ts"
      ],
      "open_questions": [
        "Should we use approach A or B for the caching layer?"
      ],
      "estimated_effort": "SMALL | MEDIUM | LARGE",
      "deadline": "<ISO 8601 or null>"
    },
    "priority": "HIGH"
  }
}

Handoff Acceptance

The receiving agent must acknowledge with an ACK:

{
  "type": "ACK",
  "payload": {
    "action": "HANDOFF_ACCEPTED",
    "data": {
      "understood_task": "My understanding of the task in my own words",
      "planned_approach": "How I intend to tackle this",
      "estimated_completion": "My estimate for completion",
      "questions_for_sender": ["Any clarifying questions"]
    }
  }
}

If the receiving agent cannot handle the task:

{
  "type": "ERROR",
  "payload": {
    "action": "HANDOFF_REJECTED",
    "data": {
      "reason": "Why I cannot accept this handoff",
      "suggestion": "Alternative agent or approach",
      "partial_capability": "What parts I COULD handle"
    }
  }
}

Handoff Chain Tracking

Maintain a chain array on every task recording which agents have worked on it:

{
  "task_id": "abc-123",
  "chain": [
    {"agent": "coordinator", "action": "CREATED", "timestamp": "2025-01-15T10:00:00Z"},
    {"agent": "researcher", "action": "WORKED", "timestamp": "2025-01-15T10:05:00Z", "duration_seconds": 120},
    {"agent": "writer", "action": "HANDOFF_RECEIVED", "timestamp": "2025-01-15T10:07:00Z"},
    {"agent": "writer", "action": "WORKED", "timestamp": "2025-01-15T10:15:00Z", "duration_seconds": 480},
    {"agent": "reviewer", "action": "HANDOFF_RECEIVED", "timestamp": "2025-01-15T10:16:00Z"},
    {"agent": "reviewer", "action": "COMPLETED", "timestamp": "2025-01-15T10:20:00Z", "duration_seconds": 240}
  ]
}

The chain provides full traceability for:

• Debugging failures (which agent introduced an issue).
• Performance analysis (which stage took longest).
• Quality tracking (which agent's output needed revision).

Operations: Commands, Best Practices, Monitoring, Security

Reference for coordination commands, best practices, observability, and security boundaries.

Coordination Commands

The user or a supervisor agent can issue these high-level commands:

Best Practices

Task Decomposition

• Break tasks into pieces where each piece can be completed by one agent independently.
• Give each subtask clear inputs, outputs, and success criteria.
• Prefer pipeline over fan-out when order matters.
• Prefer fan-out over pipeline when tasks are independent.

Context Discipline

• Write findings incrementally, not all at the end.
• Include a timestamp on every write to shared context.
• Keep sections self-contained (another agent should understand a section without external context).
• Keep the conclusions section as the canonical current state of truth.

Handoff Quality

• A handoff is only as good as its context_so_far field.
• Always include what was tried and what failed to save the receiving agent from repeating work.
• Make success criteria measurable, not vague.
• When handing off due to failure, be explicit about what went wrong.

Agent Prompt Engineering

Structure prompts spawned via the Agent tool as:

1. IDENTITY: "You are [Agent Name], a [Role]."
2. CONTEXT: "Read .a2a-context.json at [path] for your assignment."
3. TASK: Clear, specific instructions for what to do.
4. OUTPUT: "Write your results to [specific location in shared context]."
5. PROTOCOL: "Follow the A2A protocol: update your status, log messages, track your chain entry."
6. CONSTRAINTS: Any limitations, deadlines, or scope boundaries.

Avoiding Common Failures

Monitoring and Observability

Status Report

Generate a status report at any time by reading .a2a-context.json:

A2A Status Report
=================
Agents:   3 registered, 2 active, 1 idle
Tasks:    5 total, 2 completed, 2 in-progress, 1 pending
Messages: 12 in log
Chain:    coordinator -> researcher -> writer (current)

Active Tasks:
  [task-001] "Research competitors" - IN_PROGRESS (researcher) - 3m elapsed
  [task-002] "Draft comparison table" - PENDING (writer) - waiting on task-001

Recent Messages:
  10:05 researcher -> coordinator: RESPONSE "Found 8 competitor profiles"
  10:03 coordinator -> researcher: REQUEST "Research top 10 competitors in [space]"

Performance Metrics

Track across tasks:

• Time per stage: how long each agent takes.
• Handoff quality: how often receiving agents ask clarifying questions (fewer is better).
• Retry rate: how often tasks need to be retried.
• Error rate: how often agents fail.
• Chain length: average number of agents touching a task.

Security and Boundaries

Agent Isolation

• Restrict agents to reading and writing only their own section and the shared conclusions.
• Prevent any agent from modifying another agent's registration.
• Allow only the Coordinator to modify task assignments.

Sensitive Data

• Never write secrets, API keys, or credentials to .a2a-context.json.
• For tasks involving sensitive data, pass it through the Agent tool's prompt (in-memory) rather than the shared file.
• Add .a2a-context.json to .gitignore.

Scope Boundaries

• Keep agents within their declared capabilities.
• When an agent discovers it needs capabilities it does not have, have it REQUEST help or HANDOFF, never attempt to use tools it was not given.
• Have the Coordinator enforce scope by checking agent declarations before assigning tasks.

Initialization Detail

Context File Template

Create .a2a-context.json with this template:

{
  "version": "1.0.0",
  "created_at": "<now>",
  "last_modified": "<now>",
  "last_modified_by": "coordinator",
  "lock": null,
  "agents": {},
  "tasks": {},
  "sections": {},
  "conclusions": {
    "summary": "",
    "decisions": [],
    "open_questions": [],
    "next_steps": []
  },
  "message_log": []
}

Agent Bootstrapping

For each agent requested or determined to be needed:

1. Select from built-in templates or create a custom registration
2. Write the agent entry to .a2a-context.json
3. Validate: no duplicate names, capabilities cover the task requirements
4. Report the team composition to the user

Communication Patterns

Five coordination patterns for multi-agent collaboration. Select the pattern that fits the task structure.

Request/Response

The simplest pattern. Agent A asks Agent B to do something and waits for the result.

Agent A                          Agent B
  |                                |
  |--- REQUEST (do X) ----------->|
  |                                |--- ACK
  |                                |--- [works on X]
  |<-- RESPONSE (result of X) ----|
  |                                |

Implementation:

1. Agent A writes a REQUEST to .a2a-context.json message_log
2. Agent A spawns Agent B via the Agent tool with instructions:
   "You are [Agent B role]. Read .a2a-context.json for the latest REQUEST addressed to you.
    Execute the requested action. Write your RESPONSE to the message_log.
    Update your agent section with findings."
3. Agent A reads the updated .a2a-context.json to get the RESPONSE
4. Agent A proceeds with the result

Pipeline

Sequential processing where each agent transforms the output and passes it forward.

Agent A -----> Agent B -----> Agent C -----> Final Result
(research)    (draft)        (review)

Implementation:

1. Coordinator decomposes task into pipeline stages
2. For each stage:
   a. Write a HANDOFF message to the next agent
   b. Spawn the next agent via Agent tool
   c. Agent reads context, performs work, writes results
   d. Agent writes HANDOFF to next stage (or RESPONSE if final)
3. Coordinator collects final result from .a2a-context.json

Example pipeline prompt for the Coordinator:

"Orchestrate a 3-stage pipeline:

Stage 1 (researcher): Search the web for [topic], compile findings into .a2a-context.json

Stage 2 (writer): Read researcher's findings, draft a blog post, write to .a2a-context.json

Stage 3 (reviewer): Read the draft, provide feedback, write final version

Execute each stage sequentially. After all stages complete, compile the final output."

Fan-Out / Fan-In

Parallel execution where multiple agents work simultaneously, and results are collected.

              +--> Agent B (subtask 1) --+
              |                          |
Agent A ------+--> Agent C (subtask 2) --+-----> Agent A (merge)
              |                          |
              +--> Agent D (subtask 3) --+

Implementation:

1. Coordinator decomposes task into independent subtasks
2. For EACH subtask, spawn a separate Agent:
   - Each agent gets: task description, shared context reference, output location
   - Each agent writes results to its own section in .a2a-context.json
3. After ALL agents complete, Coordinator reads all sections
4. Coordinator merges results into conclusions section

To achieve parallelism, dispatch multiple Agent tool calls in a single response. Each agent runs in its own context:

[Agent call 1]: "You are researcher-alpha. Investigate [subtopic A]. Write findings to .a2a-context.json under sections.researcher-alpha."
[Agent call 2]: "You are researcher-beta. Investigate [subtopic B]. Write findings to .a2a-context.json under sections.researcher-beta."
[Agent call 3]: "You are researcher-gamma. Investigate [subtopic C]. Write findings to .a2a-context.json under sections.researcher-gamma."

After all three return, read .a2a-context.json and merge.

Conversation (Multi-Turn Dialogue)

Two agents engage in a structured back-and-forth to solve a problem collaboratively.

Agent A                          Agent B
  |                                |
  |--- "I think we should..." --->|
  |<-- "Good point, but..." ------|
  |--- "What about..." ---------->|
  |<-- "That works. Let's go" ----|
  |                                |
  [Consensus reached]

Implementation:

1. Initialize a conversation_id in .a2a-context.json
2. Set max_turns (default: 6) to prevent infinite loops
3. Agent A writes opening message (type: QUERY)
4. Spawn Agent B to read and respond
5. Read Agent B's response, spawn Agent A to continue
6. Repeat until:
   - An agent writes a message with payload.action = "CONSENSUS_REACHED"
   - max_turns is exhausted
   - An agent writes an ERROR
7. Coordinator extracts the conclusion from the final messages

Conversation rules:

• Each turn must advance the discussion (no repeating previous points).
• Agents must explicitly state agreement or disagreement.
• If max_turns is reached without consensus, escalate to a supervisor or the user.

Supervisor Pattern

One agent monitors and redirects others. The supervisor coordinates and does not do the work itself.

              Supervisor
             /    |    \
            /     |     \
        Agent A  Agent B  Agent C

Supervisor responsibilities:

1. Decompose the task into subtasks. 2. Assign each subtask to the best-matched agent (via discovery). 3. Monitor progress by reading .a2a-context.json periodically. 4. Redirect if an agent is stuck (reassign to a different agent or provide guidance). 5. Merge results when all subtasks complete. 6. Report the final outcome.

Supervisor prompt template:

"You are the Supervisor agent. Your task: [high-level goal].

>

Protocol:

1. Read .a2a-context.json to see registered agents and their capabilities

2. Decompose the task into subtasks (write them to the tasks section)

3. Assign each subtask to the best agent

4. Spawn each agent with clear instructions

5. After agents complete, read their results

6. If any agent failed or produced low-quality results, reassign or provide feedback

7. Merge all results into the conclusions section

8. Write the final summary

>

You must NOT do the work yourself. Delegate everything."

A2A Protocol Specification

Defines the message format, message types, message lifecycle, shared context file, and concurrency safeguards for the Agent-to-Agent protocol.

Message Format

Conform every inter-agent message to this schema:

{
  "id": "<uuid>",
  "from": "<agent_name>",
  "to": "<agent_name | '*' for broadcast>",
  "type": "REQUEST | RESPONSE | HANDOFF | BROADCAST | QUERY | ACK | ERROR",
  "timestamp": "<ISO 8601>",
  "conversation_id": "<uuid linking related messages>",
  "parent_message_id": "<id of message this responds to, or null>",
  "payload": {
    "action": "<what is being requested or reported>",
    "data": {},
    "priority": "LOW | NORMAL | HIGH | CRITICAL"
  },
  "context": {
    "task_id": "<uuid>",
    "chain": ["<ordered list of agents who have touched this task>"],
    "shared_refs": ["<keys into shared context>"]
  },
  "metadata": {
    "ttl_seconds": 300,
    "retry_count": 0,
    "max_retries": 3
  }
}

Message Types

Message Lifecycle

REQUEST  -->  ACK  -->  [processing]  -->  RESPONSE
REQUEST  -->  ACK  -->  [processing]  -->  ERROR
HANDOFF  -->  ACK  -->  [agent B takes over]
QUERY    -->  RESPONSE (lightweight, no ownership transfer)
BROADCAST --> [no response expected, agents act on it if relevant]

Shared Context File: .a2a-context.json

Treat this file at the project root (or specified working directory) as the single source of truth. All agents read from and write to it.

{
  "version": "1.0.0",
  "created_at": "<ISO 8601>",
  "last_modified": "<ISO 8601>",
  "last_modified_by": "<agent_name>",
  "lock": null,
  "agents": {
    "<agent_name>": {
      "role": "<string>",
      "capabilities": ["<list>"],
      "tools": ["<list>"],
      "status": "IDLE | WORKING | BLOCKED | COMPLETED | FAILED",
      "registered_at": "<ISO 8601>",
      "last_active": "<ISO 8601>"
    }
  },
  "tasks": {
    "<task_id>": {
      "description": "<string>",
      "status": "PENDING | IN_PROGRESS | BLOCKED | COMPLETED | FAILED | HANDED_OFF",
      "assigned_to": "<agent_name>",
      "created_by": "<agent_name>",
      "created_at": "<ISO 8601>",
      "updated_at": "<ISO 8601>",
      "chain": ["<agent_name>"],
      "result": null,
      "error": null
    }
  },
  "sections": {
    "<agent_name>": {
      "findings": [],
      "notes": "",
      "artifacts": []
    }
  },
  "conclusions": {
    "summary": "",
    "decisions": [],
    "open_questions": [],
    "next_steps": []
  },
  "message_log": []
}

Atomic Read-Modify-Write

Follow this procedure to prevent concurrent write corruption:

1. READ the full .a2a-context.json
2. CHECK the `lock` field:
   - If null, proceed
   - If locked by another agent AND lock is < 30 seconds old, WAIT and retry (up to 3 times)
   - If locked by another agent AND lock is > 30 seconds old, BREAK the lock (stale lock recovery)
3. ACQUIRE lock: set `lock` to { "agent": "<your_name>", "acquired_at": "<ISO 8601>" }
4. WRITE the updated file with your changes
5. RELEASE lock: set `lock` back to null
6. WRITE the final file

Read with cat .a2a-context.json, then modify in memory and write the complete file via the Write tool in a single operation. Because Claude Code agents execute sequentially rather than truly concurrently, treat the lock mechanism primarily as a protocol safeguard for future multi-process scenarios. In practice, agents coordinate through the Agent tool's sequential dispatch.

Context Size Management

When .a2a-context.json exceeds 50KB:

1. Summarize completed task results (replace verbose data with summaries). 2. Archive the full message_log to .a2a-context-archive-<timestamp>.json. 3. Keep only the last 20 messages in the active log. 4. Compress agent sections: keep only current findings, archive historical data.

Run summarization via the Agent tool:

"Read .a2a-context.json. The file is too large. Summarize all completed task results to 2-3 sentences each. Archive the message log. Preserve all active tasks, agent registrations, and conclusions. Write the compressed version back."

Agent Registry, Discovery, and Templates

Covers agent registration, capability-based discovery, and ready-to-use agent templates.

Agent Registration

Register every agent before it participates. Write registration to the agents section of .a2a-context.json:

{
  "name": "research-agent",
  "role": "Senior Researcher",
  "capabilities": [
    "web_search",
    "document_analysis",
    "fact_verification",
    "source_evaluation",
    "summarization"
  ],
  "tools": ["WebSearch", "WebFetch", "Read", "Grep", "Glob"],
  "specialization": "Finding, verifying, and synthesizing information from multiple sources",
  "accepts_handoffs_from": ["*"],
  "max_concurrent_tasks": 1
}

Capability Discovery

When an agent needs help, query the registry. Example request: "I need an agent that can review code for security vulnerabilities."

Discovery algorithm:

1. Parse the request to extract required capabilities
   - Keywords: "review code" -> code_review, "security" -> security_analysis, "vulnerabilities" -> vulnerability_detection
2. Score each registered agent:
   - Exact capability match: +10 points per match
   - Partial match (semantic similarity): +5 points
   - Tool availability: +3 points per relevant tool
   - Agent status IDLE: +5 points (prefer available agents)
   - Agent status WORKING: -5 points (avoid overloading)
3. Return the top-scoring agent(s) with match reasoning

Perform discovery via the Agent tool:

"Read .a2a-context.json and find the best agent to handle this request: [description]. Score agents on capability match, tool availability, and current status. Return the agent name and your reasoning."

Built-In Agent Templates

Instantiate these templates for common multi-agent workflows.

Research Agent:

{
  "name": "researcher",
  "role": "Information Gatherer",
  "capabilities": ["web_search", "document_analysis", "summarization", "fact_checking"],
  "tools": ["WebSearch", "WebFetch", "Read", "Grep", "Glob"],
  "specialization": "Gathering and synthesizing information from diverse sources"
}

Writer Agent:

{
  "name": "writer",
  "role": "Content Creator",
  "capabilities": ["drafting", "editing", "formatting", "tone_adjustment", "structuring"],
  "tools": ["Read", "Write", "Grep"],
  "specialization": "Transforming research and outlines into polished written content"
}

Code Agent:

{
  "name": "coder",
  "role": "Software Engineer",
  "capabilities": ["code_generation", "debugging", "refactoring", "testing", "architecture"],
  "tools": ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
  "specialization": "Writing, debugging, and optimizing code across languages"
}

Review Agent:

{
  "name": "reviewer",
  "role": "Quality Assurance",
  "capabilities": ["code_review", "security_analysis", "performance_analysis", "best_practices"],
  "tools": ["Read", "Grep", "Glob", "Bash"],
  "specialization": "Auditing code and content for quality, security, and correctness"
}

Coordinator Agent:

{
  "name": "coordinator",
  "role": "Project Manager",
  "capabilities": ["task_decomposition", "delegation", "progress_tracking", "conflict_resolution"],
  "tools": ["Read", "Write", "Agent", "Bash"],
  "specialization": "Breaking down complex tasks and orchestrating agent collaboration"
}

Practical Workflow Implementations

Worked end-to-end examples of common multi-agent workflows.

Research + Writer Pipeline

Use case: Research a topic and produce a polished article.

Step 1: Initialize shared context

Create .a2a-context.json with:
- Register "researcher" agent (capabilities: web_search, summarization)
- Register "writer" agent (capabilities: drafting, editing)
- Register "editor" agent (capabilities: proofreading, fact_checking)
- Create task: { description: "Research and write article on [topic]" }

Step 2: Dispatch Researcher

Use Agent tool:
"You are the Research Agent. Your task:
 1. Read .a2a-context.json for your assignment
 2. Search the web for authoritative sources on [topic]
 3. Compile findings: key facts, statistics, expert quotes, counterarguments
 4. Write your findings to .a2a-context.json under sections.researcher
 5. Create a HANDOFF message for the writer with:
    - task: 'Write a 1500-word article based on my research'
    - context_so_far: [your compiled findings]
    - success_criteria: ['Accurate', 'Engaging', 'Well-structured', 'Cites sources']
 6. Update task status to HANDED_OFF"

Step 3: Dispatch Writer

Use Agent tool:
"You are the Writer Agent. Your task:
 1. Read .a2a-context.json for the HANDOFF from the researcher
 2. Review all research findings in sections.researcher
 3. Draft a compelling article: hook, body sections, conclusion
 4. Write the draft to sections.writer.artifacts
 5. Create a HANDOFF to the editor
 6. Update task chain"

Step 4: Dispatch Editor

Use Agent tool:
"You are the Editor Agent. Your task:
 1. Read the draft from sections.writer.artifacts
 2. Check: factual accuracy, clarity, grammar, flow, tone
 3. Make corrections and improvements
 4. Write the final version to conclusions
 5. Mark task as COMPLETED"

Step 5: Coordinator collects final article from conclusions

Code + Review Workflow

Use case: Write a feature and have it reviewed before merging.

Step 1: Initialize context with coder and reviewer agents

Step 2: Dispatch Coder
"You are the Code Agent. Your task:
 1. Read .a2a-context.json for the feature request
 2. Implement the feature following the codebase's patterns
 3. Write tests for your implementation
 4. Log all files modified in the HANDOFF to the reviewer
 5. Include: what you built, design decisions, known limitations"

Step 3: Dispatch Reviewer
"You are the Review Agent. Your task:
 1. Read the HANDOFF from the coder
 2. Review EVERY file listed in files_modified
 3. Check for: security issues, performance problems, code style, test coverage
 4. Write your review as structured feedback:
    - MUST FIX: [blocking issues]
    - SHOULD FIX: [important improvements]
    - NICE TO HAVE: [suggestions]
    - APPROVED: [yes/no]
 5. If not approved, create a HANDOFF back to the coder with specific fix requests"

Step 4: If review fails, iterate (max 3 rounds)

Step 5: Final APPROVED status written to conclusions

Sales + Technical Specialist Handoff

Use case: A sales agent qualifies a lead and routes technical questions to a specialist.

Step 1: Register agents
- "sales-agent": capabilities: [lead_qualification, objection_handling, relationship_building]
- "technical-agent": capabilities: [architecture_review, integration_planning, security_assessment]

Step 2: Sales Agent processes the lead
"You are the Sales Agent. Your prospect: [company/person info].
 1. Qualify using BANT framework (Budget, Authority, Need, Timeline)
 2. Identify technical questions you cannot answer
 3. HANDOFF technical questions to the technical agent with:
    - Prospect context and pain points
    - Specific technical questions asked
    - What has been promised so far (be precise -- do not overcommit)
    - Tone and relationship context"

Step 3: Technical Agent provides answers
"You are the Technical Agent. A sales colleague needs technical support.
 1. Read the HANDOFF from sales-agent
 2. Research and answer each technical question with accuracy
 3. Provide: architecture diagrams (as text), integration steps, security considerations
 4. Flag any questions where the answer might be a dealbreaker
 5. RESPONSE back to sales-agent with answers formatted for customer-facing use"

Step 4: Sales Agent incorporates answers and continues the deal