Struct A2aClient 

pub struct A2aClient { /* private fields */ }

HTTP client for the A2A protocol.

A2aClient wraps a reqwest::Client and provides typed methods for the four A2A JSON-RPC operations: message/send, message/stream, tasks/get, and tasks/cancel. Each call optionally accepts a bearer token for authentication.

Security

new requires an explicit SecurityPolicy so a call site can never silently inherit a permissive default by omission (issue #6553) — use SecurityPolicy::hardened() for production, or new_insecure to opt into SecurityPolicy::permissive() explicitly for local/dev use. with_security can still override the policy after construction. When either flag is enabled, each request is sent through a dedicated per-request reqwest::Client with redirects disabled and, when ssrf_protection is on, the connection pinned to the exact addresses that were validated (no re-resolution at connect time).

Examples

use zeph_a2a::{A2aClient, SecurityPolicy, SendMessageParams, Message};

let client = A2aClient::new(reqwest::Client::new(), SecurityPolicy::hardened());

let params = SendMessageParams {
    message: Message::user_text("Summarize this page."),
    configuration: None,
};
let task = client.send_message("https://agent.example.com/a2a", params, Some("tok")).await?;
println!("Task state: {:?}", task.status.state);

Implementations

impl A2aClient

pub fn new(client: Client, security: SecurityPolicy) -> Self

Create a new A2aClient with an explicit SecurityPolicy.

The policy is a mandatory argument (issue #6553) so a call site states its security intent at construction time instead of silently inheriting a permissive default by omission. Use SecurityPolicy::hardened() for production deployments, or new_insecure to opt into SecurityPolicy::permissive() explicitly for local/dev use.

Examples

use zeph_a2a::{A2aClient, SecurityPolicy};

let client = A2aClient::new(reqwest::Client::new(), SecurityPolicy::hardened());

pub fn new_insecure(client: Client) -> Self

Create a new A2aClient with SecurityPolicy::permissive() — no TLS enforcement or SSRF protection.

Suitable only for local development against trusted, non-adversarial endpoints (e.g. http://localhost). Production code should call new with an explicit policy instead of relying on this insecure default.

Examples

use zeph_a2a::A2aClient;

let client = A2aClient::new_insecure(reqwest::Client::new());

pub fn with_security(self, policy: SecurityPolicy) -> Self

Configure the SecurityPolicy for this client.

Overrides whatever policy was set at construction time (new or new_insecure). This method uses the builder pattern and can be chained directly after either constructor.

Examples

use zeph_a2a::{A2aClient, SecurityPolicy};

let client = A2aClient::new_insecure(reqwest::Client::new())
    .with_security(SecurityPolicy::hardened());

pub fn with_request_timeout(self, timeout: Duration) -> Self

Set the per-request timeout for RPC and streaming connection calls (default: 30 seconds).

Applied to the full send + JSON response parse in rpc_call, and to the initial HTTP send() in stream_message. The SSE body stream after connection is intentionally unbounded — streams can legitimately run for a long time.

pub fn with_ibct_key(self, key: IbctKey) -> Self

Configure an IBCT signing key so every request carries a scoped X-Zeph-IBCT header alongside the bearer token.

The token is scoped to the exact endpoint string passed to send_message/ get_task/cancel_task/stream_message, and to the request’s task_id — params.id for get_task/cancel_task, message.task_id for send_message/ stream_message (the empty-string sentinel when the message has no task_id yet, i.e. it starts a brand-new task the server has not assigned an ID to).

Issuance failures (e.g. this crate compiled without the ibct feature) are logged and the request proceeds without the header — the server decides whether to reject it.

Examples

use zeph_a2a::{A2aClient, IbctKey};

let key = IbctKey { key_id: "k1".into(), key_bytes: b"secret".to_vec() };
let client = A2aClient::new_insecure(reqwest::Client::new()).with_ibct_key(key);

pub fn with_ibct_ttl(self, ttl: Duration) -> Self

Set the TTL for issued IBCT tokens (default: 5 minutes). Has no effect unless with_ibct_key is also configured.

pub async fn send_message( &self, endpoint: &str, params: SendMessageParams, token: Option<&str>, ) -> Result<Task, A2aError>

Errors

Returns A2aError on network, JSON, or JSON-RPC errors, or A2aError::Timeout if the request exceeds the configured request_timeout.

pub async fn stream_message( &self, endpoint: &str, params: SendMessageParams, token: Option<&str>, ) -> Result<TaskEventStream, A2aError>

Errors

Returns A2aError on network failure or if the SSE connection cannot be established.

pub async fn get_task( &self, endpoint: &str, params: TaskIdParams, token: Option<&str>, ) -> Result<Task, A2aError>

Errors

Returns A2aError on network, JSON, or JSON-RPC errors, or A2aError::Timeout if the request exceeds the configured request_timeout.

pub async fn cancel_task( &self, endpoint: &str, params: TaskIdParams, token: Option<&str>, ) -> Result<Task, A2aError>

Errors

Returns A2aError on network, JSON, or JSON-RPC errors, or A2aError::Timeout if the request exceeds the configured request_timeout.