cleveragents-core/docs/v3.7.0-a2a-protocol.md

# CleverAgents v3.7.0 Agent-to-Agent Communication (A2A) Protocol

## Overview

The Agent-to-Agent Communication (A2A) protocol in CleverAgents v3.7.0 enables sophisticated multi-agent orchestration through a robust, standards-compliant messaging system.

## Protocol Specification

The A2A protocol is based on JSON-RPC 2.0 with extensions for agent-specific features:

- **Standard**: JSON-RPC 2.0 (https://www.jsonrpc.org/specification)
- **Transport**: HTTP, WebSocket, stdio, gRPC
- **Encoding**: JSON
- **Authentication**: Bearer tokens, mTLS
- **Message Routing**: Agent registry-based routing

## Message Format

### Request Message

```json
{
  "jsonrpc": "2.0",
  "method": "automation.execute",
  "params": {
    "automation_id": "auto-123",
    "context": {
      "project_id": "proj-456",
      "user_id": "user-789"
    },
    "timeout": 300
  },
  "id": "msg-abc123"
}
```

### Response Message

```json
{
  "jsonrpc": "2.0",
  "result": {
    "status": "success",
    "automation_id": "auto-123",
    "duration": 45.23,
    "output": {
      "records_processed": 1000,
      "errors": 0
    }
  },
  "id": "msg-abc123"
}
```

### Error Response

```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": {
      "error_type": "AUTOMATION_FAILED",
      "details": "Automation execution failed: timeout after 300s"
    }
  },
  "id": "msg-abc123"
}
```

## Transport Layers

### HTTP Transport

HTTP is the default transport for A2A communication.

```yaml
a2a:
  transport: http
  host: 0.0.0.0
  port: 8000
  ssl:
    enabled: true
    cert_file: /path/to/cert.pem
    key_file: /path/to/key.pem
  timeout: 30
  max_connections: 100
```

### WebSocket Transport

WebSocket enables bidirectional communication for real-time updates.

```yaml
a2a:
  transport: websocket
  host: 0.0.0.0
  port: 8001
  ssl:
    enabled: true
    cert_file: /path/to/cert.pem
    key_file: /path/to/key.pem
```

### gRPC Transport

gRPC transport provides high-performance communication.

```yaml
a2a:
  transport: grpc
  host: 0.0.0.0
  port: 50051
  ssl:
    enabled: true
    cert_file: /path/to/cert.pem
    key_file: /path/to/key.pem
```

## Authentication

### Bearer Token Authentication

```python
from cleveragents.a2a import A2AClient

client = A2AClient(
    agent_id='local-agent',
    api_key='sk-...',
    base_url='http://localhost:8000'
)

result = await client.call_agent(
    agent_id='remote-agent',
    method='automation.execute',
    params={'automation_id': 'auto-123'}
)
```

### mTLS Authentication

```python
from cleveragents.a2a import A2AClient

client = A2AClient(
    agent_id='local-agent',
    base_url='https://localhost:8000',
    ssl_cert='/path/to/client-cert.pem',
    ssl_key='/path/to/client-key.pem',
    ssl_ca='/path/to/ca-cert.pem'
)
```

## Error Handling

Standard JSON-RPC error codes with custom extensions for A2A:

- **-32001**: AGENT_NOT_FOUND
- **-32002**: AGENT_UNAVAILABLE
- **-32003**: TIMEOUT
- **-32004**: AUTHENTICATION_FAILED
- **-32005**: AUTHORIZATION_FAILED
- **-32006**: AUTOMATION_FAILED

## Multi-Agent Orchestration

```python
from cleveragents.a2a import Orchestrator

async def orchestrate_workflow():
    orchestrator = Orchestrator()
    
    workflow = orchestrator.create_workflow('data-pipeline')
    
    workflow.add_step(
        'extract',
        agent_id='agent-1',
        method='data.extract',
        params={'source': 'database'}
    )
    
    workflow.add_step(
        'transform',
        agent_id='agent-2',
        method='data.transform',
        params={'format': 'json'},
        depends_on=['extract']
    )
    
    workflow.add_step(
        'load',
        agent_id='agent-3',
        method='data.load',
        params={'destination': 'warehouse'},
        depends_on=['transform']
    )
    
    result = await orchestrator.execute_workflow(workflow)
    return result
```

## Best Practices

1. **Keep Registry Updated**: Regularly update agent registry with current agents
2. **Implement Retry Logic**: Use exponential backoff for retries
3. **Use HTTPS**: Always use HTTPS in production
4. **Enable mTLS**: Use mutual TLS for agent-to-agent communication
5. **Connection Pooling**: Reuse connections for multiple requests
6. **Batch Requests**: Use batch requests for multiple operations
7. **Audit Logging**: Log all A2A communication for audit purposes

---

**Last Updated**: April 2024
**Version**: 3.7.0