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

{
  "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

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

Error Response

{
  "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.

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.

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.

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

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

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

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