A2A Protocol JSON Specification

The A2A protocol is defined through a set of JSON schemas that specify the structure of agent cards, messages, sessions, and artifacts. This document provides the complete JSON specification for implementing A2A-compatible agents and clients.

Agent Card Schema

The agent card is a JSON document that describes an agent's capabilities, endpoints, and metadata. Here's the full schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "description", "version", "api", "auth"],
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the agent"
    },
    "description": {
      "type": "string",
      "description": "A description of the agent's purpose and capabilities"
    },
    "version": {
      "type": "string",
      "description": "The version of the agent implementation"
    },
    "api": {
      "type": "object",
      "required": ["type", "url"],
      "properties": {
        "type": {
          "type": "string",
          "enum": ["a2a"],
          "description": "The type of API this agent implements"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "The base URL for API calls to this agent"
        },
        "version": {
          "type": "string",
          "description": "The version of the A2A protocol implemented by this agent"
        }
      }
    },
    "auth": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["none", "api_key", "oauth", "jwt", "custom"],
          "description": "The authentication mechanism required by this agent"
        },
        "instructions": {
          "type": "string",
          "description": "Instructions for authenticating with this agent"
        }
      }
    },
    "capabilities": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["type", "description"],
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of capability"
          },
          "description": {
            "type": "string",
            "description": "A description of what this capability does"
          },
          "parameters": {
            "type": "object",
            "description": "Parameters for this capability"
          }
        }
      }
    },
    "contact": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the contact person or organization"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL for the agent's documentation or support"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Email address for support"
        }
      }
    },
    "pricing": {
      "type": "object",
      "properties": {
        "model": {
          "type": "string",
          "enum": ["free", "pay_per_request", "subscription", "custom"],
          "description": "The pricing model for this agent"
        },
        "details": {
          "type": "string",
          "description": "Details about pricing structure"
        }
      }
    }
  }
}

Session Schema

Sessions represent ongoing conversations between clients and agents. Here's the schema for session objects:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "created_at", "status"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the session"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when this session was created"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when this session was last updated"
    },
    "status": {
      "type": "string",
      "enum": ["active", "completed", "error"],
      "description": "Current status of the session"
    },
    "metadata": {
      "type": "object",
      "description": "Optional metadata associated with this session"
    }
  }
}

Message Schema

Messages are the units of communication in the A2A protocol. Here's the schema for message objects:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "role", "content", "created_at"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the message"
    },
    "role": {
      "type": "string",
      "enum": ["user", "agent", "system"],
      "description": "The role of the sender of this message"
    },
    "content": {
      "type": "string",
      "description": "The content of the message"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when this message was created"
    },
    "in_reply_to": {
      "type": "string",
      "description": "ID of the message this is in reply to, if applicable"
    },
    "metadata": {
      "type": "object",
      "description": "Optional metadata associated with this message"
    },
    "artifacts": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/artifact"
      },
      "description": "Artifacts attached to this message"
    }
  },
  "definitions": {
    "artifact": {
      "type": "object",
      "required": ["id", "type", "data"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the artifact"
        },
        "type": {
          "type": "string",
          "description": "MIME type or custom type of the artifact"
        },
        "data": {
          "description": "The content of the artifact, format depends on type"
        },
        "name": {
          "type": "string",
          "description": "Optional name of the artifact"
        },
        "description": {
          "type": "string",
          "description": "Optional description of the artifact"
        }
      }
    }
  }
}

API Request/Response Schemas

Create Session Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "metadata": {
      "type": "object",
      "description": "Optional metadata for the new session"
    }
  }
}

Create Session Response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["session"],
  "properties": {
    "session": {
      "$ref": "#/definitions/session"
    }
  }
}

Send Message Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["role", "content"],
  "properties": {
    "role": {
      "type": "string",
      "enum": ["user", "system"],
      "description": "The role of the sender of this message"
    },
    "content": {
      "type": "string",
      "description": "The content of the message"
    },
    "in_reply_to": {
      "type": "string",
      "description": "ID of the message this is in reply to, if applicable"
    },
    "metadata": {
      "type": "object",
      "description": "Optional metadata associated with this message"
    },
    "artifacts": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/artifact"
      },
      "description": "Artifacts attached to this message"
    }
  }
}

Send Message Response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["message"],
  "properties": {
    "message": {
      "$ref": "#/definitions/message"
    }
  }
}

Get Session Messages Response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["messages"],
  "properties": {
    "messages": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/message"
      }
    },
    "pagination": {
      "type": "object",
      "properties": {
        "next_cursor": {
          "type": "string",
          "description": "Cursor for next page of results, if available"
        },
        "prev_cursor": {
          "type": "string",
          "description": "Cursor for previous page of results, if available"
        }
      }
    }
  }
}

Error Response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["error"],
  "properties": {
    "error": {
      "type": "object",
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "string",
          "description": "Error code"
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message"
        },
        "details": {
          "type": "object",
          "description": "Additional error details"
        }
      }
    }
  }
}

Schema Extensions

The A2A protocol allows for schema extensions through custom properties and the metadata fields. Extensions should follow these guidelines:

Custom properties should use a namespace prefix to avoid conflicts
Core schema properties should never be overridden
Extensions should be documented in the agent card

Example of a custom extension for a financial capability:

{
  "capabilities": [
    {
      "type": "financial.payment_processing",
      "description": "Process credit card payments",
      "parameters": {
        "supported_currencies": ["USD", "EUR", "GBP"],
        "transaction_limit": 10000
      }
    }
  ]
}

Multimodal Content

The A2A protocol supports multimodal content through artifacts. Artifacts can represent various types of content:

Text Artifact

{
  "id": "art_abc123",
  "type": "text/plain",
  "data": "This is a plain text artifact",
  "name": "notes.txt"
}

JSON Data Artifact

{
  "id": "art_def456",
  "type": "application/json",
  "data": {
    "key1": "value1",
    "key2": "value2"
  },
  "name": "data.json"
}

Image Artifact (Base64 encoded)

{
  "id": "art_ghi789",
  "type": "image/jpeg",
  "data": "base64:iVBORw0KGgoAAAANSUhEUgAAAAUA...",
  "name": "image.jpg"
}

URL Reference Artifact

{
  "id": "art_jkl012",
  "type": "url/reference",
  "data": "https://example.com/resource.pdf",
  "name": "reference.pdf"
}

API Endpoints

The A2A protocol defines these standardized RESTful endpoints:

Agent Card Endpoint

GET /card

Sessions Endpoints

POST /sessions               # Create a new session
GET /sessions/{sessionId}    # Get session details
DELETE /sessions/{sessionId} # End a session

Messages Endpoints

POST /sessions/{sessionId}/messages    # Send a message
GET /sessions/{sessionId}/messages     # Get session messages

Streaming Endpoint (Optional)

GET /sessions/{sessionId}/stream     # SSE stream for real-time updates

Implementation Guidance

When implementing the A2A protocol:

Validate All JSON: Always validate incoming and outgoing JSON against the schema
Handle Unknown Properties: Be tolerant of unknown properties to support future extensions
Follow HTTP Standards: Use appropriate HTTP methods and status codes
Include Content-Type Headers: Always specify Content-Type: application/json
Timestamp Format: Use ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ) for all timestamps
Unique IDs: Generate globally unique IDs for sessions, messages, and artifacts
Error Handling: Return structured error responses with appropriate HTTP status codes

Versioning

The A2A protocol uses semantic versioning (MAJOR.MINOR.PATCH):

MAJOR version changes indicate breaking changes
MINOR version changes add functionality in a backwards-compatible manner
PATCH version changes make backwards-compatible bug fixes

Agents should specify their supported protocol version in their agent card.

Reference Validation Tools

The A2A repository includes validation tools for the JSON schema:

JavaScript validation library
Command-line validator
Online validation tool

These tools help ensure compliance with the A2A protocol specification.

Conclusion

This document provides the complete JSON specification for the A2A protocol. By adhering to these schemas, developers can create interoperable agents that can communicate with any A2A-compatible client or agent.

JSON Specification

Table of Contents