A2A Development Patterns
Before writing code
Fetch live docs:
- Fetch
https://a2a-protocol.org/latest/specification/ for the latest protocol details
- Web-search
a2a protocol best practices multi-agent architecture for community patterns
- Web-search
site:github.com a2aproject A2A samples patterns for reference architectures
- Web-search
multi-agent system design patterns for general multi-agent architecture guidance
Conceptual Architecture
Orchestration Topologies
Hub-and-Spoke (Orchestrator)
A central coordinator agent delegates subtasks to specialist agents:
┌→ Research Agent
Coordinator Agent ──┼→ Analysis Agent
└→ Writing Agent
- Pros: Centralized control, clear task routing, easy to monitor
- Cons: Single point of failure, coordinator bottleneck
- Use when: Well-defined subtask decomposition, need for aggregation
Peer-to-Peer (Mesh)
Agents discover and communicate directly with each other:
Agent A ←→ Agent B
↕ ↕
Agent C ←→ Agent D
- Pros: No single point of failure, flexible
- Cons: Complex routing, harder to monitor, potential loops
- Use when: Agents are loosely coupled, dynamic discovery needed
Pipeline (Chain)
Tasks flow through a sequence of agents:
Input → Agent A → Agent B → Agent C → Output
- Pros: Simple flow, easy to reason about, composable
- Cons: Sequential latency, failure in one stage blocks all
- Use when: Clear transformation stages, ETL-like workflows
Hierarchical (Tree)
Manager agents delegate to team agents, which may further delegate:
CEO Agent
├── Marketing Manager Agent
│ ├── Content Agent
│ └── SEO Agent
└── Engineering Manager Agent
├── Frontend Agent
└── Backend Agent
- Pros: Natural decomposition, scoped authority, scalable
- Cons: Deep hierarchies add latency, complex coordination
- Use when: Large organizations of agents, domain separation
Idempotency
Design A2A interactions to be idempotent:
- Use deterministic task IDs (hash of input + context) when possible
- Handle duplicate
message/send requests gracefully
- Store task results for replay on retry
- Use request IDs for deduplication at the transport level
Observability
Multi-agent systems need deep observability:
Distributed tracing:
- Propagate trace IDs through A2A task metadata
- Log entry/exit for each agent in the chain
- Use OpenTelemetry or similar for cross-agent tracing
Metrics:
- Task latency per agent
- Task success/failure rates
- Message volume and throughput
- Active task count per agent
- Error code distribution
Logging:
- Log all JSON-RPC requests/responses (with sensitive data redacted)
- Include task IDs and request IDs in all log entries
- Log state transitions with timestamps
Agent Registries
For systems with many agents:
- Centralized registry — Agents register their Agent Cards; clients query by skill/tag
- DNS-based discovery — Agent Cards at well-known URLs
- Service mesh — Use infrastructure-level service discovery
Versioning
A2A agents evolve over time:
- Agent Card version — Update when skills or capabilities change
- Skill versioning — Individual skills can be versioned
- Protocol version — Track which A2A spec version you implement
- Breaking changes — Update the Agent Card URL or version for breaking changes
- Backward compatibility — Support old and new message formats during transitions
Security Patterns
- Zero trust — Authenticate every agent-to-agent call
- Least privilege — Agents only get access to the skills they need
- Audit trail — Log all cross-agent interactions for compliance
- Secret management — Use vaults for API keys and credentials, never hardcode
Production Deployment
- Health checks — Implement
/health endpoints alongside the A2A endpoint
- Graceful shutdown — Complete or cancel in-flight tasks before stopping
- Scaling — A2A servers are stateless per-request; task store handles state
- Load balancing — Standard HTTP load balancing works for A2A endpoints
- Rate limiting — Protect agents from being overwhelmed by requests
- Circuit breakers — Stop calling failing agents, use fallbacks
Error Recovery Patterns
- Retry with backoff — Transient failures, exponential backoff
- Fallback agents — If primary agent fails, try an alternative
- Dead letter queue — Store failed tasks for later analysis/replay
- Compensation — If a multi-step workflow fails midway, undo completed steps
- Timeout escalation — If a task is stuck, escalate to a human or different agent
Best Practices
- Start simple — hub-and-spoke before mesh
- Design for failure — every agent call can fail
- Make agents stateless where possible — state lives in the task store
- Use structured DataParts for inter-agent data, not serialized text
- Monitor everything — you can't debug what you can't see
- Version your Agent Cards and document changes
- Test the full topology, not just individual agents
- Set SLOs for agent response times and success rates
Fetch the latest A2A specification and community patterns before implementing multi-agent architectures.
1---2name: a2a-dev-patterns3description: Apply A2A cross-cutting development patterns — orchestration topologies, idempotency, observability, agent registries, versioning, and production deployment. Use when architecting multi-agent systems or solving cross-cutting concerns.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/a2a-dev-patterns7---89# A2A Development Patterns1011## Before writing code1213**Fetch live docs**:141. Fetch `https://a2a-protocol.org/latest/specification/` for the latest protocol details152. Web-search `a2a protocol best practices multi-agent architecture` for community patterns163. Web-search `site:github.com a2aproject A2A samples patterns` for reference architectures174. Web-search `multi-agent system design patterns` for general multi-agent architecture guidance1819## Conceptual Architecture2021### Orchestration Topologies2223#### Hub-and-Spoke (Orchestrator)24A central coordinator agent delegates subtasks to specialist agents:25```26 ┌→ Research Agent27Coordinator Agent ──┼→ Analysis Agent28 └→ Writing Agent29```30- **Pros**: Centralized control, clear task routing, easy to monitor31- **Cons**: Single point of failure, coordinator bottleneck32- **Use when**: Well-defined subtask decomposition, need for aggregation3334#### Peer-to-Peer (Mesh)35Agents discover and communicate directly with each other:36```37Agent A ←→ Agent B38 ↕ ↕39Agent C ←→ Agent D40```41- **Pros**: No single point of failure, flexible42- **Cons**: Complex routing, harder to monitor, potential loops43- **Use when**: Agents are loosely coupled, dynamic discovery needed4445#### Pipeline (Chain)46Tasks flow through a sequence of agents:47```48Input → Agent A → Agent B → Agent C → Output49```50- **Pros**: Simple flow, easy to reason about, composable51- **Cons**: Sequential latency, failure in one stage blocks all52- **Use when**: Clear transformation stages, ETL-like workflows5354#### Hierarchical (Tree)55Manager agents delegate to team agents, which may further delegate:56```57CEO Agent58├── Marketing Manager Agent59│ ├── Content Agent60│ └── SEO Agent61└── Engineering Manager Agent62 ├── Frontend Agent63 └── Backend Agent64```65- **Pros**: Natural decomposition, scoped authority, scalable66- **Cons**: Deep hierarchies add latency, complex coordination67- **Use when**: Large organizations of agents, domain separation6869### Idempotency7071Design A2A interactions to be idempotent:72- Use deterministic task IDs (hash of input + context) when possible73- Handle duplicate `message/send` requests gracefully74- Store task results for replay on retry75- Use request IDs for deduplication at the transport level7677### Observability7879Multi-agent systems need deep observability:8081**Distributed tracing:**82- Propagate trace IDs through A2A task metadata83- Log entry/exit for each agent in the chain84- Use OpenTelemetry or similar for cross-agent tracing8586**Metrics:**87- Task latency per agent88- Task success/failure rates89- Message volume and throughput90- Active task count per agent91- Error code distribution9293**Logging:**94- Log all JSON-RPC requests/responses (with sensitive data redacted)95- Include task IDs and request IDs in all log entries96- Log state transitions with timestamps9798### Agent Registries99100For systems with many agents:101- **Centralized registry** — Agents register their Agent Cards; clients query by skill/tag102- **DNS-based discovery** — Agent Cards at well-known URLs103- **Service mesh** — Use infrastructure-level service discovery104105### Versioning106107A2A agents evolve over time:108- **Agent Card version** — Update when skills or capabilities change109- **Skill versioning** — Individual skills can be versioned110- **Protocol version** — Track which A2A spec version you implement111- **Breaking changes** — Update the Agent Card URL or version for breaking changes112- **Backward compatibility** — Support old and new message formats during transitions113114### Security Patterns115116- **Zero trust** — Authenticate every agent-to-agent call117- **Least privilege** — Agents only get access to the skills they need118- **Audit trail** — Log all cross-agent interactions for compliance119- **Secret management** — Use vaults for API keys and credentials, never hardcode120121### Production Deployment122123- **Health checks** — Implement `/health` endpoints alongside the A2A endpoint124- **Graceful shutdown** — Complete or cancel in-flight tasks before stopping125- **Scaling** — A2A servers are stateless per-request; task store handles state126- **Load balancing** — Standard HTTP load balancing works for A2A endpoints127- **Rate limiting** — Protect agents from being overwhelmed by requests128- **Circuit breakers** — Stop calling failing agents, use fallbacks129130### Error Recovery Patterns131132- **Retry with backoff** — Transient failures, exponential backoff133- **Fallback agents** — If primary agent fails, try an alternative134- **Dead letter queue** — Store failed tasks for later analysis/replay135- **Compensation** — If a multi-step workflow fails midway, undo completed steps136- **Timeout escalation** — If a task is stuck, escalate to a human or different agent137138### Best Practices139140- Start simple — hub-and-spoke before mesh141- Design for failure — every agent call can fail142- Make agents stateless where possible — state lives in the task store143- Use structured DataParts for inter-agent data, not serialized text144- Monitor everything — you can't debug what you can't see145- Version your Agent Cards and document changes146- Test the full topology, not just individual agents147- Set SLOs for agent response times and success rates148149Fetch the latest A2A specification and community patterns before implementing multi-agent architectures.