a2a-types

a2a-types

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

Version Compatibility

Crate Version	A2A Protocol Version	Notes
0.1.0 - 0.1.x	0.3.0	Initial implementation

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.1"

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

MIT