a2a-mcp-integration

What this skill does

# A2A and MCP Integration Patterns

**Purpose:** Provide integration patterns, configuration examples, and best practices for combining Agent-to-Agent Protocol with Model Context Protocol in multi-agent systems.

**Activation Triggers:**
- A2A + MCP integration setup
- Hybrid protocol architecture
- Agent-to-agent + agent-to-tool communication
- Composite multi-agent systems
- Protocol compatibility questions
- Cross-protocol authentication
- Combined SDK usage

**Protocol Roles:**
- **A2A Protocol:** Agent-to-agent communication and task delegation
- **MCP:** Agent-to-tool communication and resource access
- **Combined:** Agents communicate via A2A while accessing tools via MCP

## Architecture Overview

### Why Combine A2A and MCP?

A2A and MCP are complementary protocols:

- **MCP** standardizes how agents connect to tools, APIs, and data sources
- **A2A** standardizes how agents communicate and coordinate with each other
- **Together** they enable agents to collaborate while accessing shared resources

### Integration Patterns

1. **Hierarchical Agent Systems**
   - Coordinator agent uses A2A to delegate tasks
   - Worker agents use MCP to access tools
   - Results flow back through A2A

2. **Federated Tool Access**
   - Multiple agents communicate via A2A
   - Each agent has MCP tool access
   - Agents share tool results through A2A messages

3. **Resource-Sharing Networks**
   - Agents discover each other via A2A
   - Agents expose MCP servers to each other
   - Dynamic tool delegation through agent network

## Quick Start

### Python Integration

```bash
# Install both SDKs
./scripts/install-python-integration.sh

# Validate installation
./scripts/validate-python-integration.sh

# Run example
python examples/python-hybrid-agent.py
```

### TypeScript Integration

```bash
# Install both SDKs
./scripts/install-typescript-integration.sh

# Validate installation
./scripts/validate-typescript-integration.sh

# Run example
ts-node examples/typescript-hybrid-agent.ts
```

## Configuration

### Environment Setup

Both protocols require environment configuration:

```bash
# A2A Configuration
A2A_API_KEY=your_a2a_key_here
A2A_BASE_URL=https://a2a.example.com

# MCP Configuration
MCP_SERVER_URL=http://localhost:3000
MCP_TRANSPORT=stdio

# Integration Settings
HYBRID_AGENT_ID=agent-001
HYBRID_AGENT_NAME=hybrid-coordinator
ENABLE_A2A=true
ENABLE_MCP=true
```

See `templates/env-integration-template.txt` for complete configuration.

### Authentication

Handle authentication for both protocols:

1. **Separate Credentials:** Each protocol uses its own auth
2. **Shared Identity:** Agent identity spans both protocols
3. **Token Forwarding:** Pass credentials through A2A messages (when appropriate)

See `templates/auth-hybrid-template.txt` for patterns.

## Integration Patterns

### Pattern 1: Coordinator-Worker with Shared Tools

**Architecture:**
- Coordinator agent receives tasks
- Delegates via A2A to worker agents
- Workers use MCP tools to complete tasks
- Results return via A2A

**Template:** `templates/coordinator-worker-pattern.py`

**Use Case:** Complex workflows requiring specialized agents with tool access

### Pattern 2: Peer-to-Peer with Tool Sharing

**Architecture:**
- Agents communicate as peers via A2A
- Each agent exposes MCP server
- Agents can request tools from each other
- Distributed tool access

**Template:** `templates/peer-tool-sharing-pattern.ts`

**Use Case:** Decentralized systems where agents have different capabilities

### Pattern 3: Agent Mesh with Centralized Tools

**Architecture:**
- Agents form A2A communication mesh
- Centralized MCP server provides tools
- All agents access same tool set
- Coordination via A2A, execution via MCP

**Template:** `templates/mesh-centralized-tools-pattern.py`

**Use Case:** Teams of agents working with shared infrastructure

### Pattern 4: Layered Protocol Stack

**Architecture:**
- MCP at base layer for tool access
- A2A at orchestration layer for coordination
- Application logic at top layer
- Clean separation of concerns

**Template:** `templates/layered-stack-pattern.ts`

**Use Case:** Enterprise systems requiring protocol isolation

## Scripts

### Installation Scripts

- `install-python-integration.sh` - Install Python A2A + MCP SDKs
- `install-typescript-integration.sh` - Install TypeScript A2A + MCP SDKs
- `install-java-integration.sh` - Install Java A2A + MCP SDKs

### Validation Scripts

- `validate-python-integration.sh` - Verify Python integration setup
- `validate-typescript-integration.sh` - Verify TypeScript integration setup
- `validate-protocol-compatibility.sh` - Check protocol version compatibility

### Setup Scripts

- `setup-hybrid-agent.sh` - Initialize hybrid agent environment
- `setup-mcp-server.sh` - Configure MCP server for A2A agents
- `setup-agent-discovery.sh` - Configure A2A agent discovery with MCP tools

## Templates

### Configuration Templates

- `env-integration-template.txt` - Environment variables for both protocols
- `auth-hybrid-template.txt` - Authentication configuration
- `agent-config-hybrid.json` - Agent configuration with A2A+MCP

### Code Templates

**Python:**
- `coordinator-worker-pattern.py` - Coordinator-worker implementation
- `mesh-centralized-tools-pattern.py` - Agent mesh with central MCP
- `python-hybrid-agent.py` - Basic hybrid agent

**TypeScript:**
- `peer-tool-sharing-pattern.ts` - Peer-to-peer tool sharing
- `layered-stack-pattern.ts` - Layered protocol architecture
- `typescript-hybrid-agent.ts` - Basic hybrid agent

**Java:**
- `java-hybrid-agent.java` - Basic Java integration
- `java-coordinator-pattern.java` - Coordinator pattern in Java

**Configuration:**
- `mcp-server-config.json` - MCP server configuration for A2A agents
- `a2a-agent-card.json` - Agent card with MCP tool references

## Common Integration Scenarios

### Scenario 1: Multi-Agent Data Pipeline

**Problem:** Multiple agents process data through different tools

**Solution:**
1. Coordinator receives request via A2A
2. Delegates to specialized agents (data-fetcher, data-processor, data-storage)
3. Each agent uses MCP tools for its domain
4. Results aggregate via A2A back to coordinator

**Example:** `examples/data-pipeline-integration.py`

### Scenario 2: Distributed Research Assistant

**Problem:** Research task requires web search, document analysis, and synthesis

**Solution:**
1. Agents communicate via A2A to coordinate
2. Search agent uses MCP web search tools
3. Analysis agent uses MCP document processing tools
4. Synthesis agent combines results using MCP output tools

**Example:** `examples/research-assistant-integration.ts`

### Scenario 3: Microservice-Style Agent Architecture

**Problem:** Need modular, scalable agent system

**Solution:**
1. Each agent is a microservice with A2A interface
2. Agents use MCP to access shared databases, APIs
3. Service discovery via A2A agent cards
4. Load balancing across agent instances

**Example:** `examples/microservice-agents.py`

## Error Handling

### Protocol-Specific Errors

Handle errors from both protocols:

```python
from a2a import A2AError
from mcp import MCPError

try:
    # A2A communication
    response = await a2a_client.send_task(task)

    # MCP tool execution
    result = await mcp_client.call_tool("search", params)

except A2AError as e:
    # Handle A2A communication errors
    logger.error(f"A2A error: {e}")

except MCPError as e:
    # Handle MCP tool errors
    logger.error(f"MCP error: {e}")
```

See `examples/error-handling-integration.py` for complete patterns.

### Connection Failures

Both protocols may fail independently:

1. **A2A failure, MCP working:** Agent can execute local tools
2. **MCP failure, A2A working:** Agent can delegate to others
3. **Both failing:** Implement fallback logic

See `templates/failover-pattern.py` for resilience patterns.

## Security Considerations

### Authentication Boundaries

**Separate Auth Per Protocol:**
- A2A credentials for agent communication
- MCP