Documentation

Complete guide to implementing and using the A2A Protocol

Quick Start API Reference Examples Best Practices

Introduction

What is A2A Protocol?

The A2A Protocol is an open standard for communication between AI agents, enabling seamless interaction and collaboration across different platforms and implementations. It provides a structured way for agents to discover capabilities, exchange messages, and coordinate tasks.

Key Features

  • Standardized communication format
  • Cross-platform compatibility
  • Secure message exchange

Benefits

  • Simplified agent integration
  • Enhanced interoperability
  • Scalable architecture

Quick Start

Installation

pip install 
pip install a2a-protocol
npm install 
npm install a2a-protocol

Basic Usage

Python Example 
from a2a import Agent, Task

# Initialize agent
agent = Agent(
    name="MyAgent",
    capabilities=["text_processing"]
)

# Create and process task
task = Task(
    objective="Analyze text",
    input_data="Sample text to analyze",
    requirements={
        "format": "json"
    }
)

# Execute task
result = agent.process(task)
print(result)

Try it yourself

// Analysis result will appear here

Core Concepts

Fundamental components of the A2A Protocol

Agent Card Task Message Part Artifact

Agent Card

Digital identity and capability declaration for AI agents

An Agent Card is a standardized description document for AI agents, containing their capabilities, functions, and interaction methods. It serves as a digital identity card for other agents to understand and utilize.

Basic Structure

{
  "id": "agent_123",
  "name": "Text Analysis Agent",
  "version": "1.0.0",
  "description": "NLP task processing",
  "capabilities": [
    {
      "name": "text_analysis",
      "description": "Text content analysis",
      "parameters": {
        "text": "string",
        "language": "string",
        "analysis_type": ["sentiment", "entities"]
      }
    }
  ],
  "endpoints": {
    "base_url": "https://api.example.com/agent",
    "health": "/health",
    "analyze": "/analyze"
  }
}

Key Fields

id

Unique identifier for the agent

capabilities

List of supported capabilities, each containing name, description, and parameter definitions

endpoints

API endpoints provided by the agent, including base URL and specific paths

Usage Example

from a2a import AgentCard

# Create Agent Card
agent_card = AgentCard(
    name="My Analysis Agent",
    version="1.0.0",
    description="Text analysis capabilities"
)

# Add capability
agent_card.add_capability(
    name="text_analysis",
    description="Analyze text content",
    parameters={
        "text": "string",
        "language": "string",
        "analysis_type": ["sentiment", "entities"]
    }
)

Task

Work unit in the A2A Protocol

A Task defines the work to be completed, including objectives, requirements, and completion criteria. Tasks can be broken down into subtasks and may depend on other tasks.

Basic Structure

{
  "id": "task_456",
  "type": "text_analysis",
  "objective": "Analyze customer feedback",
  "input": {
    "text": "Product is great but delivery is slow",
    "language": "en"
  },
  "requirements": {
    "analysis_types": ["sentiment", "keywords"],
    "response_format": "json",
    "deadline": "2025-04-20T12:00:00Z"
  },
  "priority": "high",
  "status": "pending"
}

Key Fields

objective

Description of the task's objective

input

Input data for the task

requirements

Specific requirements including analysis types, response format, and deadline

Message

Communication unit between agents

A Message is a communication unit between agents that can contain various types of content for task-related and general communication. Messages support multiple parts and can include different types of data.

Basic Structure

{
  "id": "msg_789",
  "type": "task_request",
  "sender": "agent_123",
  "recipient": "agent_456",
  "timestamp": "2025-04-15T10:30:00Z",
  "content": {
    "task_id": "task_456",
    "action": "analyze",
    "priority": "high"
  },
  "parts": [
    {
      "type": "text",
      "content": "Customer feedback analysis request",
      "format": "plain"
    }
  ]
}

Key Fields

type

Message type, such as task_request, response, etc.

content

Main content of the message

parts

Message components, which can be text, data, etc.

Part

Building block of messages

A Part is a building block of messages, representing different types of content such as text, images, code, or structured data. Each part has a specific type, format, and content.

Basic Structure

Text Part
{
  "type": "text",
  "content": "Example text content",
  "format": "plain",
  "language": "en",
  "encoding": "utf-8"
}
Binary Part
{
  "type": "binary",
  "content": "base64_encoded_data",
  "format": "image/png",
  "size": 1024,
  "filename": "image.png"
}

Key Fields

type

Part type, such as text, binary, etc.

format

Content format, such as plain, json, image/png, etc.

content

Actual content data

Artifact

Persistent output of agent collaboration

An Artifact is a persistent output of agent collaboration, such as documents, code, or datasets. They are stored and can be referenced in future interactions, providing a way to track and manage agent task results.

Basic Structure

{
  "id": "artifact_abc",
  "type": "analysis_report",
  "name": "Customer Feedback Analysis Q1 2025",
  "description": "Quarterly customer feedback analysis",
  "content": {
    "url": "https://storage.example.com/artifacts/abc",
    "format": "pdf",
    "size": 1048576
  },
  "metadata": {
    "created_by": "agent_123",
    "created_at": "2025-04-15T11:00:00Z",
    "version": "1.0",
    "tags": ["feedback", "analysis", "q1_2025"]
  },
  "related_tasks": ["task_456"],
  "permissions": {
    "read": ["agent_123", "agent_456"],
    "write": ["agent_123"]
  }
}

Key Fields

content

Storage location and format information of the actual content

metadata

Metadata about the artifact, such as creator, creation time, version, etc.

permissions

Access control for the artifact

API Reference

The A2A Protocol provides a standardized API interface for agent communication and task execution.

API Overview

Core endpoints for agent discovery, task management, and status checking.

{
    "endpoints": {
        "GET /agents": "List available agents",
        "POST /tasks": "Create new task",
        "GET /tasks/{task_id}": "Get task status"
    }
}

Authentication

Secure authentication methods for API access.

{
    "auth_methods": {
        "api_key": "X-API-Key header",
        "oauth2": "Bearer token"
    }
}

Error Handling

Standardized error responses and status codes.

{
    "error": {
        "code": "ERROR_CODE",
        "message": "Error description",
        "details": {}
    }
}