cleveragents-core/docs/reference/a2a_protocol_spec.md

A2A Protocol Specification

Overview

The Agent-to-Agent (A2A) Protocol is a standardized communication protocol for inter-agent communication in the CleverAgents ecosystem. It enables agents to communicate with each other, coordinate on tasks, and manage distributed workflows.

The A2A Protocol is built on top of JSON-RPC 2.0 and extends it with CleverAgents-specific methods and semantics. It supports multiple transport mechanisms including stdio (for local/embedded mode) and HTTP (for server mode).

Key Features

• JSON-RPC 2.0 Compliant: Uses the JSON-RPC 2.0 specification as the base protocol
• Extensible: Supports custom methods via the _cleveragents/ namespace
• Multi-Transport: Works over stdio, HTTP, and other transport mechanisms
• Bidirectional Communication: Supports both request-response and notification patterns
• Error Handling: Comprehensive error codes and recovery mechanisms
• Session Management: Built-in session lifecycle management
• Plan Coordination: Support for distributed plan execution and coordination

JSON-RPC 2.0 Foundation

The A2A Protocol is built on JSON-RPC 2.0, which defines:

Request Format

{
  "jsonrpc": "2.0",
  "method": "method_name",
  "params": {},
  "id": "request_id"
}

Response Format

{
  "jsonrpc": "2.0",
  "result": {},
  "id": "request_id"
}

Error Response Format

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": {}
  },
  "id": "request_id"
}

Notification Format (No Response Expected)

{
  "jsonrpc": "2.0",
  "method": "method_name",
  "params": {}
}

CleverAgents Extension Methods

All CleverAgents-specific methods use the _cleveragents/ namespace prefix to distinguish them from standard JSON-RPC methods.

Session Management Methods

_cleveragents/session/create

Creates a new session for agent communication.

Request:

{
  "jsonrpc": "2.0",
  "method": "_cleveragents/session/create",
  "params": {
    "session_id": "string",
    "agent_id": "string",
    "context": {}
  },
  "id": "request_id"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "session_id": "string",
    "created_at": "ISO8601_timestamp",
    "status": "active"
  },
  "id": "request_id"
}

_cleveragents/session/close

Closes an existing session.

Request:

{
  "jsonrpc": "2.0",
  "method": "_cleveragents/session/close",
  "params": {
    "session_id": "string"
  },
  "id": "request_id"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "session_id": "string",
    "closed_at": "ISO8601_timestamp",
    "status": "closed"
  },
  "id": "request_id"
}

Plan Management Methods

_cleveragents/plan/create

Creates a new plan for execution.

Request:

{
  "jsonrpc": "2.0",
  "method": "_cleveragents/plan/create",
  "params": {
    "session_id": "string",
    "plan_id": "string",
    "plan_definition": {},
    "metadata": {}
  },
  "id": "request_id"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "plan_id": "string",
    "session_id": "string",
    "status": "created",
    "created_at": "ISO8601_timestamp"
  },
  "id": "request_id"
}

_cleveragents/plan/execute

Executes a plan.

Request:

{
  "jsonrpc": "2.0",
  "method": "_cleveragents/plan/execute",
  "params": {
    "session_id": "string",
    "plan_id": "string",
    "execution_options": {}
  },
  "id": "request_id"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "plan_id": "string",
    "execution_id": "string",
    "status": "executing",
    "started_at": "ISO8601_timestamp"
  },
  "id": "request_id"
}

_cleveragents/plan/status

Gets the status of a plan.

Request:

{
  "jsonrpc": "2.0",
  "method": "_cleveragents/plan/status",
  "params": {
    "session_id": "string",
    "plan_id": "string"
  },
  "id": "request_id"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "plan_id": "string",
    "status": "executing|completed|failed|cancelled",
    "progress": {
      "total_steps": 10,
      "completed_steps": 5,
      "current_step": "step_name"
    },
    "result": {},
    "error": null
  },
  "id": "request_id"
}

Agent Communication Methods

_cleveragents/agent/call

Calls another agent with a request.

Request:

{
  "jsonrpc": "2.0",
  "method": "_cleveragents/agent/call",
  "params": {
    "session_id": "string",
    "target_agent_id": "string",
    "method": "string",
    "params": {},
    "timeout": 30000
  },
  "id": "request_id"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "agent_id": "string",
    "method": "string",
    "result": {},
    "execution_time_ms": 150
  },
  "id": "request_id"
}

_cleveragents/agent/notify

Sends a notification to another agent (no response expected).

Request:

{
  "jsonrpc": "2.0",
  "method": "_cleveragents/agent/notify",
  "params": {
    "session_id": "string",
    "target_agent_id": "string",
    "event": "string",
    "data": {}
  }
}

Skill Execution Methods

_cleveragents/skill/execute

Executes a skill.

Request:

{
  "jsonrpc": "2.0",
  "method": "_cleveragents/skill/execute",
  "params": {
    "session_id": "string",
    "skill_id": "string",
    "skill_params": {},
    "timeout": 30000
  },
  "id": "request_id"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "skill_id": "string",
    "status": "success|failed",
    "output": {},
    "execution_time_ms": 250
  },
  "id": "request_id"
}

Context Management Methods

_cleveragents/context/get

Retrieves context information.

Request:

{
  "jsonrpc": "2.0",
  "method": "_cleveragents/context/get",
  "params": {
    "session_id": "string",
    "context_key": "string"
  },
  "id": "request_id"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "context_key": "string",
    "value": {},
    "timestamp": "ISO8601_timestamp"
  },
  "id": "request_id"
}

_cleveragents/context/set

Sets context information.

Request:

{
  "jsonrpc": "2.0",
  "method": "_cleveragents/context/set",
  "params": {
    "session_id": "string",
    "context_key": "string",
    "value": {},
    "ttl": 3600
  },
  "id": "request_id"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "context_key": "string",
    "status": "set",
    "timestamp": "ISO8601_timestamp"
  },
  "id": "request_id"
}

Message Types and Formats

Message Envelope

All A2A messages follow a standard envelope format:

{
  "jsonrpc": "2.0",
  "method": "method_name",
  "params": {
    "session_id": "string",
    "request_id": "string",
    "timestamp": "ISO8601_timestamp",
    "version": "1.0"
  },
  "id": "unique_request_id"
}

Common Parameter Types

Session Parameters

{
  "session_id": "string",
  "agent_id": "string",
  "context": {
    "project_id": "string",
    "environment": "string",
    "metadata": {}
  }
}

Plan Parameters

{
  "plan_id": "string",
  "plan_definition": {
    "name": "string",
    "description": "string",
    "steps": [
      {
        "id": "string",
        "type": "string",
        "action": "string",
        "params": {}
      }
    ]
  }
}

Execution Parameters

{
  "execution_id": "string",
  "plan_id": "string",
  "status": "pending|executing|completed|failed|cancelled",
  "progress": {
    "total_steps": 10,
    "completed_steps": 5,
    "current_step": "string"
  },
  "result": {},
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

Transport Details

Stdio Transport (Local Mode)

The stdio transport is used for local agent communication, typically for embedded or single-process scenarios.

Characteristics:

• Uses standard input/output streams
• Synchronous request-response pattern
• No network overhead
• Suitable for local testing and development

Message Format:

<message_length>\n
<json_message>

Example:

145
{"jsonrpc":"2.0","method":"_cleveragents/session/create","params":{"session_id":"sess_123"},"id":"req_1"}

HTTP Transport (Server Mode)

The HTTP transport is used for remote agent communication over a network.

Characteristics:

• Uses HTTP/1.1 or HTTP/2
• RESTful endpoints
• Asynchronous support via webhooks
• Suitable for distributed systems

Endpoints:

POST /rpc

Main RPC endpoint for method calls.

Request:

POST /rpc HTTP/1.1
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "_cleveragents/session/create",
  "params": {},
  "id": "req_1"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "result": {},
  "id": "req_1"
}

POST /events

Event notification endpoint.

Request:

POST /events HTTP/1.1
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "_cleveragents/agent/notify",
  "params": {
    "event": "plan_completed",
    "data": {}
  }
}

GET /health

Health check endpoint.

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "healthy",
  "timestamp": "ISO8601_timestamp",
  "version": "1.0"
}

Transport Selection

The transport mechanism is selected based on the deployment mode:

• Local Mode: Uses stdio transport for direct process communication
• Server Mode: Uses HTTP transport for network communication
• Hybrid Mode: Can use both transports simultaneously

Error Handling

Standard JSON-RPC Error Codes

Code	Message	Description
-32700	Parse error	Invalid JSON was received
-32600	Invalid Request	The JSON sent is not a valid Request object
-32601	Method not found	The method does not exist or is not available
-32602	Invalid params	Invalid method parameter(s)
-32603	Internal error	Internal JSON-RPC error
-32000 to -32099	Server error	Reserved for implementation-defined server errors

CleverAgents-Specific Error Codes

Code	Message	Description
-32100	Session not found	The specified session does not exist
-32101	Plan not found	The specified plan does not exist
-32102	Agent not found	The specified agent does not exist
-32103	Skill execution failed	Skill execution failed with error
-32104	Timeout	Request timed out
-32105	Authorization failed	User is not authorized for this operation
-32106	Resource exhausted	System resource limit exceeded
-32107	Invalid state	Operation not valid in current state

Error Response Example

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32100,
    "message": "Session not found",
    "data": {
      "session_id": "sess_123",
      "timestamp": "2024-04-19T10:30:00Z",
      "request_id": "req_1"
    }
  },
  "id": "req_1"
}

Error Recovery

The A2A Protocol supports several error recovery mechanisms:

1. Automatic Retry: Failed requests can be automatically retried with exponential backoff
2. Circuit Breaker: Failing agents can be temporarily isolated to prevent cascading failures
3. Fallback: Alternative agents or skills can be used if primary ones fail
4. Checkpoint/Restore: Plan execution can be checkpointed and restored from failure points

Protocol Examples

Example 1: Creating and Executing a Plan

// Step 1: Create a session
{
  "jsonrpc": "2.0",
  "method": "_cleveragents/session/create",
  "params": {
    "session_id": "sess_abc123",
    "agent_id": "agent_main",
    "context": {
      "project_id": "proj_123",
      "environment": "production"
    }
  },
  "id": "req_1"
}

// Response
{
  "jsonrpc": "2.0",
  "result": {
    "session_id": "sess_abc123",
    "created_at": "2024-04-19T10:30:00Z",
    "status": "active"
  },
  "id": "req_1"
}

// Step 2: Create a plan
{
  "jsonrpc": "2.0",
  "method": "_cleveragents/plan/create",
  "params": {
    "session_id": "sess_abc123",
    "plan_id": "plan_xyz789",
    "plan_definition": {
      "name": "Deploy Application",
      "steps": [
        {
          "id": "step_1",
          "type": "skill",
          "action": "build_application",
          "params": {"version": "1.0"}
        },
        {
          "id": "step_2",
          "type": "skill",
          "action": "deploy_application",
          "params": {"environment": "production"}
        }
      ]
    }
  },
  "id": "req_2"
}

// Response
{
  "jsonrpc": "2.0",
  "result": {
    "plan_id": "plan_xyz789",
    "session_id": "sess_abc123",
    "status": "created",
    "created_at": "2024-04-19T10:30:05Z"
  },
  "id": "req_2"
}

// Step 3: Execute the plan
{
  "jsonrpc": "2.0",
  "method": "_cleveragents/plan/execute",
  "params": {
    "session_id": "sess_abc123",
    "plan_id": "plan_xyz789",
    "execution_options": {
      "parallel": false,
      "timeout": 3600000
    }
  },
  "id": "req_3"
}

// Response
{
  "jsonrpc": "2.0",
  "result": {
    "plan_id": "plan_xyz789",
    "execution_id": "exec_123",
    "status": "executing",
    "started_at": "2024-04-19T10:30:10Z"
  },
  "id": "req_3"
}

// Step 4: Check plan status
{
  "jsonrpc": "2.0",
  "method": "_cleveragents/plan/status",
  "params": {
    "session_id": "sess_abc123",
    "plan_id": "plan_xyz789"
  },
  "id": "req_4"
}

// Response
{
  "jsonrpc": "2.0",
  "result": {
    "plan_id": "plan_xyz789",
    "status": "completed",
    "progress": {
      "total_steps": 2,
      "completed_steps": 2,
      "current_step": null
    },
    "result": {
      "deployment_id": "deploy_456",
      "status": "success"
    },
    "error": null
  },
  "id": "req_4"
}

Example 2: Agent-to-Agent Communication

// Agent A calls Agent B
{
  "jsonrpc": "2.0",
  "method": "_cleveragents/agent/call",
  "params": {
    "session_id": "sess_abc123",
    "target_agent_id": "agent_worker",
    "method": "process_data",
    "params": {
      "data": [1, 2, 3, 4, 5],
      "operation": "sum"
    },
    "timeout": 5000
  },
  "id": "req_5"
}

// Response from Agent B
{
  "jsonrpc": "2.0",
  "result": {
    "agent_id": "agent_worker",
    "method": "process_data",
    "result": {
      "sum": 15,
      "count": 5,
      "average": 3
    },
    "execution_time_ms": 125
  },
  "id": "req_5"
}

Example 3: Skill Execution

// Execute a skill
{
  "jsonrpc": "2.0",
  "method": "_cleveragents/skill/execute",
  "params": {
    "session_id": "sess_abc123",
    "skill_id": "skill_email_sender",
    "skill_params": {
      "recipient": "user@example.com",
      "subject": "Hello",
      "body": "This is a test email"
    },
    "timeout": 10000
  },
  "id": "req_6"
}

// Response
{
  "jsonrpc": "2.0",
  "result": {
    "skill_id": "skill_email_sender",
    "status": "success",
    "output": {
      "message_id": "msg_789",
      "sent_at": "2024-04-19T10:30:30Z"
    },
    "execution_time_ms": 450
  },
  "id": "req_6"
}

Protocol Versioning

The A2A Protocol uses semantic versioning:

• Major Version: Breaking changes to the protocol
• Minor Version: Backward-compatible additions
• Patch Version: Bug fixes and non-breaking changes

Current version: 1.0.0

Security Considerations

Authentication

All A2A communications should be authenticated using:

• API keys for HTTP transport
• Session tokens for long-lived connections
• TLS/SSL for encrypted communication

Authorization

Authorization is enforced at multiple levels:

• Session-level: Who can access a session
• Plan-level: Who can execute a plan
• Skill-level: Who can execute a skill
• Agent-level: Who can call an agent

Message Integrity

All messages should include:

• Request IDs for tracking
• Timestamps for audit trails
• Digital signatures for critical operations

Related Documentation

• A2A Implementation Guide
• A2A Server Deployment Guide
• ADR-047: ACP Standard Adoption
• ADR-048: Server Application Architecture
• ADR-026: Agent Client Protocol