a2a-types

Rust implementation of the Agent-to-Agent (A2A) Protocol types.

Version Compatibility

See the A2A Protocol Releases for the specification.

Overview

This crate provides the complete type definitions for the A2A Protocol, enabling interoperability between AI agents. It includes:

• JSON-RPC 2.0 message types
• A2A protocol-specific types (Tasks, Messages, Parts)
• Error definitions
• Request/Response structures

Implementation Details

This crate is a direct implementation of the official A2A JSON Schema. It is designed to be robust, idiomatic, and correct.

Key implementation patterns include:

• serde for Serialization: All types are derived with serde::Serialize and serde::Deserialize for seamless JSON handling. Attributes like #[serde(rename = "...")] are used to map Rust's snake_case fields to the camelCase or other conventions used in the JSON schema.
• Discriminated (Tagged) Unions: For JSON anyOf structures that have a clear discriminator field (like A2ARequest which is tagged by method, or SecurityScheme tagged by type), the crate uses #[serde(tag = "...")]. This provides safe, explicit, and efficient deserialization.
• Untagged Unions: For JSON unions without a common discriminator field (like JSONRPCResponse), the crate uses #[serde(untagged)] to deserialize based on structural matching.
• Robustness:
  • #[serde(default)] is used for optional fields (especially Vec<T>) to ensure that missing fields in the JSON payload deserialize to a default empty value instead of causing an error.
  • Large enum variants are wrapped in Box<T> to keep the enum's size on the stack small and prevent potential stack overflows.

Usage

Add this to your Cargo.toml:

[dependencies]
a2a-types = "0.1.0"

Then use the types in your code:

use a2a_types::{Task, Message, MessageRole, Part, TaskState};

// Create a new message
let message = Message {
    role: MessageRole::User,
    content: vec![Part::Text {
        text: "Hello, agent!".to_string(),
        metadata: None,
    }],
    metadata: None,
};

// Work with task states
let state = TaskState::Working;

Types

The crate is organized around the core concepts of the A2A protocol.

Agent Discovery

• AgentCard: The central manifest describing an agent's capabilities, skills, and security requirements.
• AgentSkill: A distinct capability or function the agent can perform.
• AgentCapabilities: Optional features supported by the agent (e.g., streaming).
• SecurityScheme: A tagged enum describing authentication methods (API Key, OAuth2, etc.).

Core Protocol Objects

• Task: The stateful unit of work, tracking status, history, and results.
• Message: A single communication turn between a client and an agent.
• Part: A discriminated enum for content within a Message or Artifact (Text, File, Data).
• Artifact: An output (e.g., a document, image) generated by a Task.
• TaskState: An enum representing the task lifecycle (Submitted, Working, Completed, etc.).

JSON-RPC and A2A Requests

• A2ARequest: The primary struct for all client requests. It wraps the A2ARequestPayload.
• A2ARequestPayload: A tagged enum where each variant represents a specific A2A method (e.g., SendMessage, GetTask, CancelTask).
• JSONRPCResponse: An enum representing all possible success or error responses from the agent.
• A2AError: An enum representing all A2A-specific and standard JSON-RPC errors.

License

Apache-2.0