A2A Protocol Architecture

The A2A protocol (Agent-to-Agent) is designed for seamless communication between AI agents, regardless of their implementation or hosting environment. This document provides an architectural overview of the protocol's components and design principles.

Core Architectural Components

The A2A protocol architecture consists of several key components:

1. Agents

Agents are the primary actors in the A2A ecosystem. An agent:

• Exposes capabilities through a well-defined API
• Can process requests and generate responses
• Maintains state throughout a conversation
• Can call other agents to fulfill tasks

Agents may be specialized (performing specific tasks like booking flights) or general-purpose (handling a wide range of requests).

2. Agent Cards

Agent cards are machine-readable JSON documents that describe an agent's:

• Identity information (name, description, version)
• Capabilities and supported functions
• Authentication requirements
• API endpoint information
• Schema definitions for inputs and outputs

Agent cards serve as the "business card" for an agent, enabling discovery and integration.

3. Sessions

Sessions represent ongoing conversations between agents and/or users. A session:

• Has a unique identifier
• Contains message history
• Maintains conversation state
• Can span multiple requests

Sessions allow for stateful interactions and context preservation across multiple exchanges.

4. Messages

Messages are the units of communication in the A2A protocol. Messages:

• Are encoded in JSON format
• Have a sender and receiver
• Contain content and metadata
• May include attachments and artifacts

Messages flow between agents, forming conversations within sessions.

5. Artifacts

Artifacts are structured data objects that can be passed between agents, such as:

• Document references
• Images or media
• Structured data objects
• Executable code snippets
• Tool results

Artifacts provide a way to share complex data beyond simple text.

Protocol Flow

The typical flow in an A2A interaction follows this pattern:

1. Discovery: A client discovers an agent through its agent card
2. Session Initialization: The client initiates a session with the agent
3. Message Exchange: The client and agent exchange messages within the session
4. Capability Invocation: The agent processes messages and invokes its capabilities
5. Agent Collaboration: If needed, the agent calls other agents to fulfill the request
6. Response Generation: The agent generates responses, potentially with artifacts
7. Session Maintenance: The conversation continues with maintained context
8. Session Termination: The session is closed when the interaction is complete

Integration Patterns

A2A supports several integration patterns:

Direct Integration

Clients integrate directly with agents, establishing a one-to-one relationship:

Client → Agent

Agent Orchestration

A primary agent orchestrates multiple specialized agents:

Client → Primary Agent → Specialized Agent A
                      → Specialized Agent B
                      → Specialized Agent C

Agent Mesh

Agents form a mesh network, calling each other as needed:

Client → Agent A ↔ Agent B
             ↕       ↕
           Agent C ↔ Agent D

Gateway Pattern

A gateway aggregates multiple agents behind a unified interface:

           ┌→ Agent A
Client → Gateway → Agent B
           └→ Agent C

Technical Architecture

API Endpoints

A2A agents expose standardized API endpoints:

• /card: Returns the agent card with agent metadata
• /sessions: Manages session creation and termination
• /sessions/{sessionId}/messages: Handles message exchange

Authentication

A2A supports multiple authentication mechanisms:

• API keys
• OAuth 2.0
• JWT tokens
• Custom authentication schemes

Authentication requirements are specified in the agent card.

Error Handling

The protocol defines standard error codes and responses:

• 4xx errors for client-side issues
• 5xx errors for server-side problems
• Structured error responses with error codes and descriptions

Extension Mechanisms

A2A is designed for extensibility through:

• Custom capabilities
• Protocol extensions
• Optional features
• Versioning support

Protocol Layers

The A2A architecture can be conceptualized in layers:

1. Transport Layer: HTTP/HTTPS communication
2. Message Layer: JSON message formatting
3. Session Layer: Conversation state management
4. Capability Layer: Agent functionality
5. Discovery Layer: Agent discovery and metadata
6. Security Layer: Authentication and authorization

Implementation Considerations

When implementing A2A:

1. Security First: Always implement proper authentication and authorization
2. Stateless Design: Design agents to be horizontally scalable
3. Cache Strategically: Cache immutable resources like agent cards
4. Handle Failures: Implement robust error handling and retry mechanisms
5. Version Everything: Clearly version API endpoints and schemas
6. Document Capabilities: Provide comprehensive documentation for agent capabilities
7. Monitor Performance: Implement metrics and tracing for performance monitoring

Reference Implementations

The A2A repository contains reference implementations in multiple languages:

• TypeScript/JavaScript: Full client and server implementation
• Python: Client and server libraries
• Java: Basic client implementation
• Go: Agent server implementation

These implementations demonstrate the protocol's language-agnostic design and provide starting points for custom implementations.

Conclusion

The A2A protocol architecture provides a flexible, extensible framework for agent communication. By adhering to these architectural principles, developers can create agents that seamlessly integrate into the broader A2A ecosystem, enabling powerful agent collaboration scenarios.