a2a-protocol-types 0.3.0

A2A protocol v1.0 — pure data types, serde only, no I/O
Documentation

a2a-protocol-types

Pure A2A protocol v1.0 data types -- serde only, no I/O.

Overview

  • All A2A v1.0 wire types with zero I/O dependencies
  • Just serde + serde_json for serialization
  • Foundation crate used by a2a-protocol-client and a2a-protocol-server
  • Use this crate when you need A2A types without the full HTTP stack

Key Types

Module Key Types Purpose
agent_card AgentCard, AgentCapabilities, AgentSkill Agent discovery (/.well-known/agent.json)
task Task, TaskStatus, TaskState, TaskId, ContextId Unit of work lifecycle
message Message, Part, MessageRole, FileContent Communication with text/file/data parts
artifact Artifact, ArtifactId Discrete agent outputs
error A2aError, ErrorCode, A2aResult Protocol errors (14 codes)
jsonrpc JsonRpcRequest, JsonRpcResponse JSON-RPC 2.0 envelope
events StreamResponse, TaskStatusUpdateEvent, TaskArtifactUpdateEvent SSE streaming events
security SecurityScheme, SecurityRequirement API Key, OAuth 2.0, OpenID, mTLS
params MessageSendParams, TaskQueryParams, ListTasksParams Method parameters for all 11 A2A methods
responses SendMessageResponse, TaskListResponse Method result types
push TaskPushNotificationConfig Push notification config
extensions AgentExtension, AgentCardSignature Optional agent capabilities
signing JWS signing functions Agent card signing (feature-gated)

Features

Feature Purpose
signing Agent card signing (JWS/ES256, RFC 8785 canonicalization). Adds ring and base64.

Usage

use a2a_protocol_types::*;

// Agent card discovery
let card: AgentCard = serde_json::from_str(json)?;

// Create a message
let msg = Message {
    id: MessageId::new("msg-001"),
    role: MessageRole::User,
    parts: vec![Part::text("Hello, agent!")],
    metadata: None,
};

// Streaming events
match event {
    StreamResponse::StatusUpdate(ev) => { /* ... */ }
    StreamResponse::ArtifactUpdate(ev) => { /* ... */ }
    StreamResponse::Task(task) => { /* ... */ }
    StreamResponse::Message(msg) => { /* ... */ }
}

Protocol Constants

  • A2A_VERSION -- "1.0.0"
  • A2A_CONTENT_TYPE -- "application/a2a+json"
  • A2A_VERSION_HEADER -- "A2A-Version"

Design Notes

  • ID newtypes for type safety: TaskId, ContextId, MessageId, ArtifactId
  • #[non_exhaustive] on enums for forward-compatible additions
  • ProtoJSON naming: TaskState::Completed serializes as "TASK_STATE_COMPLETED"
  • No unsafe code: #![deny(unsafe_op_in_unsafe_fn)]
  • All types documented: #![deny(missing_docs)]
  • Property-tested: JSON ser/de round-trip verified via proptest

License

Apache-2.0