zeph_a2a/
lib.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! A2A (Agent-to-Agent) protocol client, server, and agent discovery for Zeph.
5//!
6//! This crate implements the [A2A protocol](https://google.github.io/A2A/) — a JSON-RPC 2.0
7//! based specification for communication between AI agents. It provides:
8//!
9//! - **Client** ([`A2aClient`]): sends messages and streams responses to remote A2A agents.
10//! - **Server** (`A2aServer`, feature `server`): exposes an HTTP endpoint that accepts
11//!   A2A JSON-RPC requests and streams Server-Sent Events (SSE) for real-time output.
12//! - **Discovery** ([`AgentRegistry`]): fetches and caches agent capability cards from
13//!   `/.well-known/agent.json` with configurable TTL.
14//! - **Capability cards** ([`AgentCardBuilder`]): builds [`AgentCard`] metadata describing
15//!   the agent's skills, I/O modes, and protocol version.
16//! - **IBCT** ([`Ibct`], feature `ibct`): Invocation-Bound Capability Tokens for scoped
17//!   delegation — HMAC-SHA256 signed tokens bound to a specific task and endpoint.
18//! - **JSON-RPC 2.0 types** ([`jsonrpc`]): request/response envelope types and the A2A
19//!   method name constants.
20//! - **Protocol types** ([`types`]): shared wire-format types re-exported at the crate root.
21//!
22//! # Architecture
23//!
24//! `zeph-a2a` is an optional feature-gated dependency of the main `zeph` binary. The
25//! `A2aServer` is started by `zeph-core` as a background service when `[a2a]` is enabled
26//! in config. The [`A2aClient`] is used by the agent to delegate tasks to peer agents
27//! discovered through the [`AgentRegistry`].
28//!
29//! # Features
30//!
31//! | Feature | Description |
32//! |---------|-------------|
33//! | `server` | Enables `A2aServer`, `TaskManager`, and `TaskProcessor` |
34//! | `ibct`   | Enables [`Ibct`] token issuance and verification (HMAC-SHA256) |
35//!
36//! # Examples
37//!
38//! ```rust,no_run
39//! use zeph_a2a::{A2aClient, AgentCardBuilder, AgentRegistry, SendMessageParams, Message};
40//! use std::time::Duration;
41//!
42//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
43//! // Build an agent card for this agent.
44//! let card = AgentCardBuilder::new("my-agent", "http://localhost:8080", "0.1.0")
45//!     .description("A helpful AI agent")
46//!     .streaming(true)
47//!     .build();
48//!
49//! // Discover a peer agent's capabilities.
50//! let registry = AgentRegistry::new(reqwest::Client::new(), Duration::from_secs(300));
51//! let peer_card = registry.discover("http://peer-agent.example.com").await?;
52//!
53//! // Send a message to the peer agent.
54//! let client = A2aClient::new(reqwest::Client::new());
55//! let params = SendMessageParams {
56//!     message: Message::user_text("Hello, peer agent!"),
57//!     configuration: None,
58//! };
59//! let task = client.send_message(&peer_card.url, params, None).await?;
60//! println!("Task {} in state {:?}", task.id, task.status.state);
61//! # Ok(())
62//! # }
63//! ```
64
65#![forbid(unsafe_code)]
66
67pub mod card;
68pub mod client;
69pub mod discovery;
70pub mod error;
71pub mod ibct;
72pub mod jsonrpc;
73#[cfg(feature = "server")]
74#[cfg_attr(docsrs, doc(cfg(feature = "server")))]
75pub mod server;
76pub mod types;
77
78#[cfg(test)]
79mod testing;
80
81/// A2A protocol version implemented by this crate.
82pub const A2A_PROTOCOL_VERSION: &str = "0.2.1";
83
84pub use card::AgentCardBuilder;
85pub use client::{A2aClient, TaskEvent, TaskEventStream};
86pub use discovery::AgentRegistry;
87pub use error::A2aError;
88pub use ibct::{Ibct, IbctError, IbctKey};
89pub use jsonrpc::SendMessageParams;
90#[cfg(feature = "server")]
91#[cfg_attr(docsrs, doc(cfg(feature = "server")))]
92pub use server::{A2aServer, ProcessorEvent, TaskManager, TaskProcessor};
93pub use types::*;
zeph_a2a/lib.rs

zeph_a2a/
lib.rs
