DocumentationProtocol Specification

Protocol Specification

This document provides a comprehensive overview of Google’s Agent-to-Agent (A2A) communication protocol as implemented in the A2A Node SDK.

Overview

The Agent-to-Agent (A2A) protocol is a standardized communication framework designed to enable seamless interaction between AI agents. It defines the structure, semantics, and lifecycle of agent communications.

Key Principles

  • Standardization: Common interface for all agent interactions
  • Reliability: Built-in error handling and retry mechanisms
  • Scalability: Support for high-volume agent communications
  • Extensibility: Pluggable architecture for custom implementations
  • Security: Authentication and authorization mechanisms

Protocol Architecture

Core Concepts

Agents

Agents are autonomous entities that can process tasks and communicate with other agents.

Agent Card

Every agent must provide an Agent Card that describes its capabilities:

interface AgentCard {
  id: string;                    // Unique agent identifier
  name: string;                  // Human-readable name
  description?: string;          // Agent description
  version: string;               // Agent version
  capabilities: string[];        // List of capabilities
  endpoint: string;              // Agent endpoint URL
  metadata?: Record<string, any>; // Additional metadata
  supportedTasks?: TaskDefinition[]; // Supported task types
}

Example:

{
  "id": "weather-agent-v2",
  "name": "Weather Information Agent",
  "description": "Provides current weather and forecast data",
  "version": "2.1.0",
  "capabilities": [
    "weather-current",
    "weather-forecast",
    "location-services"
  ],
  "endpoint": "https://weather.example.com",
  "metadata": {
    "author": "Weather Corp",
    "license": "MIT",
    "regions": ["US", "EU", "APAC"]
  }
}

Tasks

Tasks represent units of work that agents can execute.

Task Lifecycle

Task Structure

interface Task {
  id: string;                    // Unique task identifier
  name: string;                  // Task name/type
  description?: string;          // Task description
  status: TaskStatus;            // Current status
  input?: any;                   // Task input data
  result?: any;                  // Task result (when completed)
  error?: string;                // Error message (when failed)
  artifacts?: Artifact[];        // Generated artifacts
  createdAt: string;             // ISO 8601 timestamp
  updatedAt: string;             // ISO 8601 timestamp
  transitions?: TaskTransition[]; // Status history
}
 
type TaskStatus = 'submitted' | 'working' | 'completed' | 'failed' | 'canceled';

Example:

{
  "id": "task-12345",
  "name": "get-weather",
  "description": "Get current weather for New York",
  "status": "completed",
  "input": {
    "location": "New York, NY",
    "units": "metric"
  },
  "result": {
    "temperature": 22,
    "condition": "sunny",
    "humidity": 65
  },
  "artifacts": [
    {
      "id": "weather-data-1",
      "type": "json",
      "content": { "data": "..." },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:05Z"
}

Messages

Messages enable real-time communication between agents.

Message Structure

interface Message {
  id: string;                    // Unique message identifier
  conversationId?: string;       // Conversation grouping
  senderId: string;              // Sender agent ID
  recipientId: string;           // Recipient agent ID
  parts: MessagePart[];          // Message content parts
  timestamp: string;             // ISO 8601 timestamp
  metadata?: Record<string, any>; // Additional metadata
}
 
interface MessagePart {
  type: 'text' | 'file' | 'data';
  content: any;                  // Part-specific content
}

Example:

{
  "id": "msg-67890",
  "conversationId": "conv-123",
  "senderId": "client-agent",
  "recipientId": "weather-agent",
  "parts": [
    {
      "type": "text",
      "content": "What's the weather like in Paris?"
    }
  ],
  "timestamp": "2024-01-15T10:30:00Z",
  "metadata": {
    "priority": "normal",
    "language": "en"
  }
}

Artifacts

Artifacts are outputs generated by task execution.

interface Artifact {
  id: string;                    // Unique artifact identifier
  type: string;                  // Artifact type (text, json, file, etc.)
  content: any;                  // Artifact content
  metadata?: Record<string, any>; // Additional metadata
  createdAt: string;             // ISO 8601 timestamp
  updatedAt: string;             // ISO 8601 timestamp
}

HTTP API Specification

Agent Discovery

Get Agent Card

GET /.well-known/agent.json

Response:

{
  "id": "weather-agent",
  "name": "Weather Agent",
  "version": "1.0.0",
  "capabilities": ["weather-data"],
  "endpoint": "https://weather.example.com"
}

Discover Agents

POST /agents/discover
Content-Type: application/json
 
{
  "capabilities": ["weather-data"],
  "location": "US"
}

Response:

{
  "agents": [
    {
      "id": "weather-agent",
      "name": "Weather Agent",
      "endpoint": "https://weather.example.com",
      "capabilities": ["weather-data"]
    }
  ]
}

Task Management

Create Task

POST /tasks
Content-Type: application/json
 
{
  "name": "get-weather",
  "description": "Get weather for location",
  "input": {
    "location": "New York, NY"
  }
}

Response:

{
  "id": "task-12345",
  "name": "get-weather",
  "status": "submitted",
  "createdAt": "2024-01-15T10:30:00Z"
}

Get Task Status

GET /tasks/{taskId}

Response:

{
  "id": "task-12345",
  "name": "get-weather",
  "status": "completed",
  "result": {
    "temperature": 22,
    "condition": "sunny"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:05Z"
}

Cancel Task

DELETE /tasks/{taskId}

Response:

{
  "id": "task-12345",
  "status": "canceled",
  "updatedAt": "2024-01-15T10:31:00Z"
}

Message Exchange

Send Message

POST /messages
Content-Type: application/json
 
{
  "recipientId": "weather-agent",
  "parts": [
    {
      "type": "text",
      "content": "What's the weather in Paris?"
    }
  ]
}

Response:

{
  "id": "msg-67890",
  "status": "sent",
  "timestamp": "2024-01-15T10:30:00Z"
}

Get Messages

GET /messages?conversationId=conv-123&limit=50

Response:

{
  "messages": [
    {
      "id": "msg-67890",
      "senderId": "client-agent",
      "recipientId": "weather-agent",
      "parts": [
        {
          "type": "text",
          "content": "What's the weather in Paris?"
        }
      ],
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "hasMore": false
}

WebSocket API Specification

Connection

const ws = new WebSocket('wss://agent.example.com/ws');

Message Format

All WebSocket messages follow this format:

interface WebSocketMessage {
  type: string;                  // Message type
  id?: string;                   // Optional message ID
  data?: any;                    // Message payload
  error?: {                      // Error information
    code: string;
    message: string;
  };
}

Task Streaming

Subscribe to Task Updates

{
  "type": "task:subscribe",
  "id": "req-1",
  "data": {
    "taskId": "task-12345"
  }
}

Task Update Notification

{
  "type": "task:update",
  "data": {
    "id": "task-12345",
    "status": "working",
    "progress": 0.5,
    "updatedAt": "2024-01-15T10:30:03Z"
  }
}

Message Streaming

Subscribe to Messages

{
  "type": "message:subscribe",
  "id": "req-2",
  "data": {
    "conversationId": "conv-123"
  }
}

New Message Notification

{
  "type": "message:new",
  "data": {
    "id": "msg-67891",
    "senderId": "weather-agent",
    "parts": [
      {
        "type": "text",
        "content": "The weather in Paris is 18°C and cloudy."
      }
    ],
    "timestamp": "2024-01-15T10:30:10Z"
  }
}

Error Handling

Error Response Format

interface ErrorResponse {
  error: {
    code: string;                // Error code
    message: string;             // Human-readable message
    details?: any;               // Additional error details
    timestamp: string;           // ISO 8601 timestamp
  };
}

Standard Error Codes

Task Errors

CodeDescription
TASK_NOT_FOUNDTask with specified ID not found
TASK_ALREADY_COMPLETEDTask is already in completed state
TASK_ALREADY_CANCELEDTask is already canceled
INVALID_TASK_STATEInvalid state transition
TASK_TIMEOUTTask execution timeout
TASK_EXECUTION_FAILEDTask execution failed

Message Errors

CodeDescription
AGENT_NOT_FOUNDTarget agent not found
INVALID_MESSAGE_FORMATMessage format is invalid
MESSAGE_TOO_LARGEMessage exceeds size limit
RATE_LIMIT_EXCEEDEDToo many messages sent

General Errors

CodeDescription
AUTHENTICATION_REQUIREDAuthentication is required
AUTHORIZATION_FAILEDInsufficient permissions
VALIDATION_ERRORRequest validation failed
INTERNAL_SERVER_ERRORUnexpected server error

Error Examples

Task Not Found

{
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task with ID 'task-12345' not found",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "field": "input.location",
      "reason": "Location is required"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Authentication & Authorization

Bearer Token Authentication

Authorization: Bearer <token>

API Key Authentication

X-API-Key: <api-key>

Agent-to-Agent Authentication

Agents can authenticate using mutual TLS or signed JWTs:

interface AgentToken {
  iss: string;                   // Issuer (agent ID)
  aud: string;                   // Audience (target agent ID)
  sub: string;                   // Subject (requesting agent ID)
  exp: number;                   // Expiration timestamp
  iat: number;                   // Issued at timestamp
  capabilities: string[];        // Requested capabilities
}

Rate Limiting

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000

Rate Limit Response

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "resetTime": "2024-01-15T11:00:00Z"
    }
  }
}

Content Types

Supported Media Types

  • application/json - JSON data
  • text/plain - Plain text
  • application/octet-stream - Binary data
  • multipart/form-data - File uploads
  • application/x-ndjson - Newline-delimited JSON (streaming)

File Handling

File Upload

POST /files
Content-Type: multipart/form-data
 
--boundary
Content-Disposition: form-data; name="file"; filename="data.csv"
Content-Type: text/csv
 
[file content]
--boundary--

File Reference in Messages

{
  "type": "file",
  "content": {
    "id": "file-12345",
    "name": "data.csv",
    "mimeType": "text/csv",
    "size": 1024,
    "url": "https://agent.example.com/files/file-12345"
  }
}

Versioning

API Versioning

The A2A protocol supports versioning through:

  1. URL Path: /v1/tasks, /v2/tasks
  2. Header: Accept: application/vnd.a2a.v1+json
  3. Query Parameter: ?version=1

Compatibility

  • Backward Compatibility: New versions maintain compatibility with previous versions
  • Deprecation: Old versions are deprecated with advance notice
  • Migration: Clear migration paths provided for version upgrades

Security Considerations

Transport Security

⚠️

Always use HTTPS/WSS in production environments to ensure data encryption in transit.

  • TLS 1.2+: Minimum required version
  • Certificate Validation: Proper certificate chain validation
  • HSTS: HTTP Strict Transport Security headers

Input Validation

  • Schema Validation: All inputs validated against JSON schemas
  • Sanitization: User inputs sanitized to prevent injection attacks
  • Size Limits: Maximum payload sizes enforced

Access Control

  • Authentication: Verify agent identity
  • Authorization: Check agent permissions
  • Capability-based: Access control based on agent capabilities

Performance Guidelines

Request Optimization

  • Compression: Use gzip/deflate compression
  • Caching: Implement appropriate caching strategies
  • Connection Pooling: Reuse HTTP connections
  • Batch Operations: Group multiple operations when possible

Timeout Configuration

OperationRecommended Timeout
Agent Discovery5 seconds
Task Creation10 seconds
Task Execution5 minutes
Message Send30 seconds
File Upload2 minutes

Monitoring

  • Health Checks: Regular endpoint health monitoring
  • Metrics: Track request rates, response times, error rates
  • Logging: Comprehensive request/response logging
  • Alerting: Automated alerts for failures

Implementation Notes

SDK Compliance

The A2A Node SDK implements this specification with:

  • Full Protocol Support: All endpoints and features
  • Type Safety: TypeScript interfaces for all protocol types
  • Error Handling: Comprehensive error handling and retry logic
  • Performance: Optimized for high-throughput scenarios

Extension Points

The protocol allows for extensions through:

  • Custom Headers: Additional metadata in HTTP headers
  • Metadata Fields: Extensible metadata in core types
  • Custom Artifacts: Agent-specific artifact types
  • Middleware: Custom request/response processing

Next Steps

Server GuideExamples