a2a-patterns

What this skill does

# A2A Protocol Implementation Patterns

## Instructions

This skill provides comprehensive patterns for implementing the Agent2Agent (A2A) protocol in Google's Agent Development Kit (ADK). The A2A protocol standardizes communication between AI agents, enabling multi-agent collaboration across different platforms and frameworks.

## What is A2A?

The Agent2Agent (A2A) protocol enables AI agents to:
- Discover each other's capabilities through Agent Cards
- Communicate securely using standardized JSON-RPC messages
- Collaborate across different frameworks (CrewAI, LangGraph, ADK)
- Work across deployment platforms (Cloud Run, Agent Engine, GKE)

**Key Concept:** A2A focuses on agent-to-agent collaboration in natural modalities, complementing MCP (Model Context Protocol) which handles tool/data connections.

## Core Patterns

### 1. Exposing Agents via A2A (Server-Side)

**When to use:** Make your ADK agent available for other agents to consume

**Template:** `templates/a2a-server.py`

**Key Components:**
- `AgentCard` at `/.well-known/agent.json` - Advertises capabilities
- `AgentExecutor` - Handles incoming requests
- `DefaultRequestHandler` - Processes JSON-RPC messages
- `A2AStarletteApplication` - HTTP server implementation

**Script:** `scripts/expose-agent.sh`

### 2. Consuming External Agents (Client-Side)

**When to use:** Integrate remote A2A agents as sub-agents

**Template:** `templates/a2a-client.py`

**Key Components:**
- `A2ACardResolver` - Discovers remote agent capabilities
- `send_task` tool - Sends messages to remote agents
- Session tracking - Maintains context across interactions

**Script:** `scripts/consume-agent.sh`

### 3. Multi-Agent Communication

**When to use:** Orchestrate multiple specialized agents collaborating on complex tasks

**Template:** `templates/multi-agent-orchestration.py`

**Pattern:**
- Coordinator agent routes tasks
- Specialist agents handle specific domains
- Agent-to-agent messaging via A2A protocol
- Result aggregation and synthesis

**Example:** `examples/purchasing-concierge/`

### 4. Agent Card Configuration

**When to use:** Define agent capabilities for discovery

**Template:** `templates/agent-card.json`

**Contents:**
- Agent metadata (name, description, version)
- Capabilities and skills
- Supported modalities (text, audio, video)
- Endpoint URLs and protocol version
- Streaming support indicators

**Script:** `scripts/generate-agent-card.sh`

## Implementation Patterns

### Server-Side: Exposing an Agent

```python
# templates/a2a-server.py structure
from adk import Agent
from a2a import AgentExecutor, DefaultRequestHandler, AgentCard

class MyAgentExecutor(AgentExecutor):
    """Handle incoming A2A requests"""
    async def execute(self, request):
        # Process request using your agent
        result = await self.agent.run(request.message)
        return result

# Configure Agent Card
agent_card = AgentCard(
    name="my-agent",
    description="Agent description",
    capabilities=["skill1", "skill2"],
    endpoint="https://my-agent.example.com"
)

# Expose via HTTP
from a2a import A2AStarletteApplication

app = A2AStarletteApplication(
    executor=MyAgentExecutor(),
    card=agent_card
)
```

**Deployment:**
```bash
# Deploy to Cloud Run
bash scripts/expose-agent.sh --platform cloud-run

# Deploy to Agent Engine
bash scripts/expose-agent.sh --platform agent-engine

# Deploy to GKE
bash scripts/expose-agent.sh --platform gke
```

### Client-Side: Consuming an Agent

```python
# templates/a2a-client.py structure
from adk import Agent
from a2a import A2ACardResolver, send_task

# Discover remote agent
resolver = A2ACardResolver()
agent_card = await resolver.resolve("https://remote-agent.example.com")

# Create tool to communicate with remote agent
send_task_tool = send_task(
    agent_url=agent_card.endpoint,
    session_id="unique-session-id"
)

# Use in your agent
my_agent = Agent(
    tools=[send_task_tool],
    # ... other config
)

# Agent can now invoke remote agent
result = await my_agent.run("Ask the remote agent to do something")
```

### Multi-Agent Orchestration

```python
# templates/multi-agent-orchestration.py structure
from adk import Agent
from a2a import A2ACardResolver, send_task

# Discover specialist agents
resolver = A2ACardResolver()
research_agent = await resolver.resolve("https://research-agent.example.com")
analysis_agent = await resolver.resolve("https://analysis-agent.example.com")
writing_agent = await resolver.resolve("https://writing-agent.example.com")

# Coordinator agent
coordinator = Agent(
    name="coordinator",
    tools=[
        send_task(agent_url=research_agent.endpoint),
        send_task(agent_url=analysis_agent.endpoint),
        send_task(agent_url=writing_agent.endpoint)
    ],
    instructions="""
    You coordinate multiple specialist agents:
    1. Use research agent to gather information
    2. Use analysis agent to process findings
    3. Use writing agent to synthesize results
    """
)

# Execute multi-agent workflow
result = await coordinator.run("Research and write a report on AI agents")
```

## Agent Card Structure

```json
{
  "id": "my-agent",
  "name": "My Agent",
  "description": "Description of agent capabilities",
  "version": "1.0.0",
  "url": "https://my-agent.example.com",
  "capabilities": {
    "skills": [
      {
        "name": "skill1",
        "description": "First skill description"
      },
      {
        "name": "skill2",
        "description": "Second skill description"
      }
    ],
    "modalities": ["text", "image"],
    "streaming": true
  },
  "protocol": {
    "version": "0.3",
    "transport": "grpc"
  }
}
```

**Generation:**
```bash
bash scripts/generate-agent-card.sh \
  --name "my-agent" \
  --description "Agent description" \
  --skills "skill1,skill2" \
  --modalities "text,image" \
  --url "https://my-agent.example.com"
```

## Protocol Configuration

### gRPC Transport (A2A v0.3+)

```python
# templates/grpc-config.py
from a2a import A2AStarletteApplication, GrpcTransport

app = A2AStarletteApplication(
    executor=MyAgentExecutor(),
    transport=GrpcTransport(
        host="0.0.0.0",
        port=50051,
        secure=True,
        cert_file="/path/to/cert.pem",
        key_file="/path/to/key.pem"
    )
)
```

### Security Cards (A2A v0.3+)

```python
# templates/security-card.py
from a2a import SecurityCard, sign_card

# Create security card
security_card = SecurityCard(
    issuer="my-organization",
    audience=["trusted-agent-1", "trusted-agent-2"],
    permissions=["read", "write"]
)

# Sign the card
signed_card = sign_card(
    card=security_card,
    private_key="/path/to/private-key.pem"
)
```

### JSON-RPC Message Format

**Request:**
```json
{
  "id": "request-uuid",
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "message": "Task description",
    "session_id": "session-uuid",
    "context": {}
  }
}
```

**Response:**
```json
{
  "id": "request-uuid",
  "jsonrpc": "2.0",
  "result": {
    "message": "Agent response",
    "artifacts": [],
    "status": "completed"
  }
}
```

## Scripts

### 1. Expose Agent via A2A

```bash
bash scripts/expose-agent.sh --platform cloud-run --region us-central1
```

**What it does:**
- Generates Agent Card at `/.well-known/agent.json`
- Creates Dockerfile with A2A server
- Deploys to specified platform
- Configures networking and security
- Returns agent endpoint URL

### 2. Consume Remote Agent

```bash
bash scripts/consume-agent.sh --url https://remote-agent.example.com
```

**What it does:**
- Resolves Agent Card from remote URL
- Validates capabilities
- Generates client code
- Creates `send_task` tool wrapper
- Provides integration example

### 3. Generate Agent Card

```bash
bash scripts/generate-agent-card.sh \
  --name "my-agent" \
  --description "Agent description" \
  --skills "research,analysis,writing"
```

**What it does:**
- Creates JSON Agent Card
- Validates against A2A schema
- Generates `/.well-known/agent.json`
-