Skip to main content

agent_infra_sdk/
lib.rs

1//! Unified client for Agent Infra services.
2//!
3//! Context, Trace, Runtime Identity, Model, Delivery, Evaluate, and Environment
4//! APIs use one Gateway endpoint. Runtime filesystem access is modeled through
5//! Environment Space resources rather than the removed managed Workspace API.
6#![cfg_attr(
7    not(any(
8        feature = "delivery",
9        feature = "source",
10        feature = "admin",
11        feature = "agents",
12        feature = "execution",
13        feature = "evaluate",
14        feature = "context",
15        feature = "memory",
16        feature = "workspace",
17        feature = "gateway",
18        feature = "model",
19        feature = "trace",
20        feature = "runtime-identity"
21    )),
22    allow(dead_code, unused_variables)
23)]
24//!
25//! # Usage
26//!
27//! ```rust,ignore
28//! use agent_infra_sdk::InfraClient;
29//!
30//! let client = InfraClient::new("http://127.0.0.1:5200")?;
31//!
32//! let messages = client
33//!     .context()
34//!     .recent_messages("conv-1", Some(50), &[])
35//!     .await?;
36//! ```
37
38use std::time::Duration;
39
40#[cfg(feature = "admin")]
41mod admin;
42#[cfg(feature = "agents")]
43mod agent;
44#[cfg(feature = "context")]
45mod compression;
46#[cfg(feature = "context")]
47mod context;
48#[cfg(feature = "delivery")]
49mod delivery;
50#[cfg(feature = "workspace")]
51mod environment;
52#[cfg(feature = "evaluate")]
53mod evaluate;
54#[cfg(feature = "execution")]
55mod execution;
56#[cfg(all(feature = "execution", feature = "context", feature = "trace"))]
57mod execution_projection;
58#[cfg(feature = "gateway")]
59mod gateway;
60#[cfg(feature = "memory")]
61mod memory;
62#[cfg(feature = "model")]
63mod model;
64mod operation;
65#[cfg(feature = "runtime-identity")]
66mod runtime_identity;
67#[cfg(feature = "source")]
68mod source;
69#[cfg(feature = "trace")]
70mod trace;
71#[cfg(feature = "memory")]
72pub use agent_memory_contract as memory_contract;
73#[cfg(feature = "memory")]
74pub use memory::MemoryClient;
75mod transport;
76mod transport_body;
77mod transport_support;
78
79#[cfg(feature = "admin")]
80pub use admin::AdminClient;
81#[cfg(feature = "agents")]
82pub use agent::AgentClient;
83#[cfg(feature = "context")]
84pub use agent_context_contract as context_contract;
85#[cfg(feature = "delivery")]
86pub use agent_delivery_contract as delivery_contract;
87#[cfg(feature = "evaluate")]
88pub use agent_evaluate_contract as evaluate_contract;
89#[cfg(feature = "execution")]
90pub use agent_execution_contract as execution_contract;
91#[cfg(feature = "admin")]
92pub use agent_model_contract as model_contract;
93#[cfg(feature = "agents")]
94pub use agent_registry_contract as agent_contract;
95#[cfg(feature = "runtime-identity")]
96pub use agent_runtime_identity_contract as runtime_identity_contract;
97#[cfg(feature = "source")]
98pub use agent_source_contract as source_contract;
99#[cfg(feature = "trace")]
100pub use agent_trace_contract as trace_contract;
101#[cfg(feature = "workspace")]
102pub use agent_workspace_contract as workspace_contract;
103#[cfg(feature = "context")]
104#[deprecated(note = "prompt compression belongs to runtime/context assembly")]
105pub use compression::{ContextCompressionConfig, compress_context};
106#[cfg(feature = "context")]
107pub use context::ContextClient;
108#[cfg(feature = "delivery")]
109pub use delivery::DeliveryClient;
110#[cfg(feature = "workspace")]
111pub use environment::EnvironmentClient;
112#[cfg(feature = "evaluate")]
113pub use evaluate::EvaluateClient;
114#[cfg(feature = "execution")]
115pub use execution::ExecutionClient;
116#[cfg(all(feature = "execution", feature = "context", feature = "trace"))]
117pub use execution_projection::{ExecutionProjectionWorker, ProjectionWorkerResult};
118#[cfg(all(feature = "gateway", feature = "runtime-identity"))]
119pub use gateway::RuntimeRecoveryCredentials;
120#[cfg(all(feature = "gateway", feature = "runtime-identity"))]
121pub use gateway::RuntimeWorkloadCredentials;
122#[cfg(feature = "gateway")]
123pub use gateway::{DelegationLeaseCredentials, GatewayClient, GatewayExchangeCredentials};
124#[cfg(feature = "gateway")]
125pub use infra_api_gateway_contract as gateway_contract;
126#[cfg(feature = "model")]
127pub use model::{ModelClient, ModelStream};
128pub use operation::{
129    CancellationToken, OperationHandle, OperationObservation, OperationPoller, OperationProgress,
130    WaitOptions,
131};
132#[cfg(feature = "runtime-identity")]
133pub use runtime_identity::RuntimeIdentityClient;
134#[cfg(feature = "source")]
135pub use source::SourceClient;
136#[cfg(feature = "trace")]
137pub use trace::TraceClient;
138pub use transport::{
139    BearerCredential, CallOptions, ClientOptions, CredentialError, CredentialsProvider,
140    InfraClientError, NoopTelemetry, RetryPolicy, StaticCredentials, TelemetryEvent,
141    TelemetryObserver, TelemetryPhase,
142};
143
144use reqwest::Client;
145use transport::ServiceEndpoint;
146
147/// Unified developer client for Agent Infra.
148///
149/// Gateway-backed domains share one HTTP connection pool. Domain service
150/// addresses are intentionally not part of the public configuration surface;
151/// only the Workspace data plane may be replaced by an injected port.
152#[derive(Clone, Debug)]
153pub struct InfraClient {
154    #[cfg(feature = "admin")]
155    admin: AdminClient,
156    #[cfg(feature = "agents")]
157    agents: AgentClient,
158    #[cfg(feature = "execution")]
159    execution: ExecutionClient,
160    #[cfg(feature = "delivery")]
161    delivery: DeliveryClient,
162    #[cfg(feature = "source")]
163    source: SourceClient,
164    #[cfg(feature = "evaluate")]
165    evaluate: EvaluateClient,
166    #[cfg(feature = "gateway")]
167    gateway: GatewayClient,
168    #[cfg(feature = "model")]
169    model: ModelClient,
170    #[cfg(feature = "context")]
171    context: ContextClient,
172    #[cfg(feature = "memory")]
173    memory: MemoryClient,
174    #[cfg(feature = "trace")]
175    trace: TraceClient,
176    #[cfg(feature = "workspace")]
177    environment: EnvironmentClient,
178    #[cfg(feature = "runtime-identity")]
179    runtime_identity: RuntimeIdentityClient,
180}
181
182impl InfraClient {
183    /// Start configuring a client for one Agent Infra Gateway.
184    #[cfg(feature = "memory")]
185    pub fn memory(&self) -> &MemoryClient {
186        &self.memory
187    }
188
189    pub fn builder(gateway_base_url: impl Into<String>) -> InfraClientBuilder {
190        InfraClientBuilder::new(gateway_base_url)
191    }
192
193    /// Create a client with default transport policy.
194    pub fn new(gateway_base_url: impl Into<String>) -> Result<Self, InfraClientError> {
195        Self::builder(gateway_base_url).build()
196    }
197
198    /// Create an unauthenticated client for the local Gateway.
199    pub fn local() -> Result<Self, InfraClientError> {
200        Self::new("http://127.0.0.1:5200")
201    }
202
203    #[cfg(feature = "admin")]
204    pub fn admin(&self) -> &AdminClient {
205        &self.admin
206    }
207
208    #[cfg(feature = "agents")]
209    pub fn agents(&self) -> &AgentClient {
210        &self.agents
211    }
212
213    #[cfg(feature = "execution")]
214    pub fn execution(&self) -> &ExecutionClient {
215        &self.execution
216    }
217
218    #[cfg(feature = "delivery")]
219    pub fn delivery(&self) -> &DeliveryClient {
220        &self.delivery
221    }
222
223    #[cfg(feature = "source")]
224    pub fn source(&self) -> &SourceClient {
225        &self.source
226    }
227
228    #[cfg(feature = "evaluate")]
229    pub fn evaluate(&self) -> &EvaluateClient {
230        &self.evaluate
231    }
232
233    #[cfg(feature = "context")]
234    pub fn context(&self) -> &ContextClient {
235        &self.context
236    }
237
238    #[cfg(feature = "workspace")]
239    pub fn environment(&self) -> &EnvironmentClient {
240        &self.environment
241    }
242
243    #[cfg(feature = "gateway")]
244    pub fn gateway(&self) -> &GatewayClient {
245        &self.gateway
246    }
247
248    #[cfg(feature = "model")]
249    pub fn model(&self) -> &ModelClient {
250        &self.model
251    }
252
253    #[cfg(feature = "trace")]
254    pub fn trace(&self) -> &TraceClient {
255        &self.trace
256    }
257
258    #[cfg(feature = "runtime-identity")]
259    pub fn runtime_identity(&self) -> &RuntimeIdentityClient {
260        &self.runtime_identity
261    }
262}
263
264fn build_http_client(options: &ClientOptions) -> Result<Client, InfraClientError> {
265    if options.connect_timeout.is_zero() || options.connect_timeout > Duration::from_secs(60) {
266        return Err(InfraClientError::InvalidOptions {
267            message: "connect_timeout must be within 1ns..=60s".into(),
268        });
269    }
270    if options.request_timeout.is_zero() || options.request_timeout > Duration::from_secs(600) {
271        return Err(InfraClientError::InvalidOptions {
272            message: "request_timeout must be within 1ns..=600s".into(),
273        });
274    }
275    if !(1..=1024).contains(&options.max_idle_connections_per_host) {
276        return Err(InfraClientError::InvalidOptions {
277            message: "max_idle_connections_per_host must be within 1..=1024".into(),
278        });
279    }
280    if options.pool_idle_timeout.is_zero() || options.pool_idle_timeout > Duration::from_secs(600) {
281        return Err(InfraClientError::InvalidOptions {
282            message: "pool_idle_timeout must be within 1ns..=600s".into(),
283        });
284    }
285    if !(1..=1024 * 1024 * 1024).contains(&options.max_response_bytes) {
286        return Err(InfraClientError::InvalidOptions {
287            message: "max_response_bytes must be within 1 byte..=1 GiB".into(),
288        });
289    }
290    if !(1..=8).contains(&options.retry.max_attempts)
291        || options.retry.base_delay > options.retry.max_delay
292        || options.retry.max_delay > Duration::from_secs(30)
293    {
294        return Err(InfraClientError::InvalidOptions {
295            message: "retry requires 1..=8 attempts and 0 <= base_delay <= max_delay <= 30s".into(),
296        });
297    }
298    if options.user_agent.is_empty()
299        || options.user_agent.len() > 256
300        || reqwest::header::HeaderValue::from_str(&options.user_agent).is_err()
301    {
302        return Err(InfraClientError::InvalidOptions {
303            message: "user_agent must be a valid 1..=256 byte HTTP header value".into(),
304        });
305    }
306    Client::builder()
307        .connect_timeout(options.connect_timeout)
308        .timeout(options.request_timeout)
309        .pool_idle_timeout(options.pool_idle_timeout)
310        .pool_max_idle_per_host(options.max_idle_connections_per_host)
311        // Service bearer credentials must not be replayed to redirects.
312        .redirect(reqwest::redirect::Policy::none())
313        .build()
314        .map_err(InfraClientError::ClientBuild)
315}
316
317/// Builder for the Infra SDK. Gateway-backed clients share one immutable
318/// `reqwest::Client`, one connection pool, and one Gateway endpoint.
319#[derive(Debug, Clone)]
320pub struct InfraClientBuilder {
321    gateway: ServiceEndpoint,
322    credentials: Option<std::sync::Arc<dyn CredentialsProvider>>,
323    options: ClientOptions,
324}
325
326impl InfraClientBuilder {
327    pub fn new(gateway_base_url: impl Into<String>) -> Self {
328        Self {
329            gateway: ServiceEndpoint::new(gateway_base_url),
330            credentials: None,
331            options: ClientOptions::default(),
332        }
333    }
334
335    pub fn options(mut self, options: ClientOptions) -> Self {
336        self.options = options;
337        self
338    }
339
340    pub fn credentials(mut self, provider: std::sync::Arc<dyn CredentialsProvider>) -> Self {
341        self.credentials = Some(provider);
342        self
343    }
344
345    pub fn request_timeout(mut self, timeout: std::time::Duration) -> Self {
346        self.options.request_timeout = timeout;
347        self
348    }
349
350    pub fn max_response_bytes(mut self, limit: usize) -> Self {
351        self.options.max_response_bytes = limit;
352        self
353    }
354
355    pub fn retry_policy(mut self, retry: RetryPolicy) -> Self {
356        self.options.retry = retry;
357        self
358    }
359
360    pub fn user_agent(mut self, user_agent: impl Into<String>) -> Self {
361        self.options.user_agent = user_agent.into();
362        self
363    }
364
365    pub fn telemetry(mut self, telemetry: std::sync::Arc<dyn TelemetryObserver>) -> Self {
366        self.options.telemetry = telemetry;
367        self
368    }
369
370    /// Allow plaintext service endpoints only when an authenticated service
371    /// mesh supplies the transport security boundary.
372    pub fn trusted_mesh_http(mut self, trusted: bool) -> Self {
373        self.options.trusted_mesh_http = trusted;
374        self
375    }
376
377    pub fn build(self) -> Result<InfraClient, InfraClientError> {
378        let http = build_http_client(&self.options)?;
379        let endpoint = endpoint_with_credentials(self.gateway, &self.credentials);
380        Ok(InfraClient {
381            #[cfg(feature = "admin")]
382            admin: AdminClient::new_with_endpoint(
383                http.clone(),
384                endpoint.clone(),
385                self.options.clone(),
386            ),
387            #[cfg(feature = "agents")]
388            agents: AgentClient::new_with_endpoint(
389                http.clone(),
390                endpoint.clone(),
391                self.options.clone(),
392            ),
393            #[cfg(feature = "execution")]
394            execution: ExecutionClient::new_with_endpoint(
395                http.clone(),
396                endpoint.clone(),
397                self.options.clone(),
398            ),
399            #[cfg(feature = "delivery")]
400            delivery: DeliveryClient::new_with_endpoint(
401                http.clone(),
402                endpoint.clone(),
403                self.options.clone(),
404            ),
405            #[cfg(feature = "source")]
406            source: SourceClient::new_with_endpoint(
407                http.clone(),
408                endpoint.clone(),
409                self.options.clone(),
410            ),
411            #[cfg(feature = "evaluate")]
412            evaluate: EvaluateClient::new_with_endpoint(
413                http.clone(),
414                endpoint.clone(),
415                self.options.clone(),
416            ),
417            #[cfg(feature = "gateway")]
418            gateway: GatewayClient::new_with_endpoint(
419                http.clone(),
420                endpoint.clone(),
421                self.options.clone(),
422            ),
423            #[cfg(feature = "model")]
424            model: ModelClient::new_with_endpoint(
425                http.clone(),
426                endpoint.clone(),
427                self.options.clone(),
428            ),
429            #[cfg(feature = "context")]
430            context: ContextClient::new_with_endpoint(
431                http.clone(),
432                endpoint.clone(),
433                self.options.clone(),
434            ),
435            #[cfg(feature = "memory")]
436            memory: MemoryClient::new_with_endpoint(
437                http.clone(),
438                endpoint.clone(),
439                self.options.clone(),
440            ),
441            #[cfg(feature = "trace")]
442            trace: TraceClient::new_with_endpoint(
443                http.clone(),
444                endpoint.clone(),
445                self.options.clone(),
446            ),
447            #[cfg(feature = "workspace")]
448            environment: EnvironmentClient::new_with_endpoint(
449                http.clone(),
450                endpoint.clone(),
451                self.options.clone(),
452            ),
453            #[cfg(feature = "runtime-identity")]
454            runtime_identity: RuntimeIdentityClient::new_with_endpoint(
455                http,
456                endpoint,
457                self.options,
458            ),
459        })
460    }
461}
462
463fn endpoint_with_credentials(
464    mut endpoint: ServiceEndpoint,
465    credentials: &Option<std::sync::Arc<dyn CredentialsProvider>>,
466) -> ServiceEndpoint {
467    if let Some(credentials) = credentials {
468        endpoint.credentials = Some(credentials.clone());
469    }
470    endpoint
471}