agent_uri/
lib.rs

1//! Parser and validator for the `agent://` URI scheme.
2//!
3//! This crate implements parsing, validation, and serialization of agent URIs
4//! as defined in the Agent Identity URI Scheme specification.
5//!
6//! # Overview
7//!
8//! Agent URIs provide topology-independent identity for agents with
9//! capability-based discovery. They have the structure:
10//!
11//! ```text
12//! agent://<trust-root>/<capability-path>/<agent-id>[?query][#fragment]
13//! ```
14//!
15//! # Quick Start
16//!
17//! ```rust
18//! use agent_uri::AgentUri;
19//!
20//! // Parse an agent URI
21//! let uri = AgentUri::parse(
22//!     "agent://anthropic.com/assistant/chat/llm_chat_01h455vb4pex5vsknk084sn02q"
23//! ).unwrap();
24//!
25//! // Access components
26//! assert_eq!(uri.trust_root().host_str(), "anthropic.com");
27//! assert_eq!(uri.capability_path().as_str(), "assistant/chat");
28//! assert_eq!(uri.agent_id().prefix().as_str(), "llm_chat");
29//!
30//! // Create new agent IDs
31//! use agent_uri::AgentId;
32//! let id = AgentId::new("llm_chat");
33//! println!("New agent: {}", id);
34//! ```
35//!
36//! # Builder Pattern
37//!
38//! Use the typestate builder for compile-time enforced construction:
39//!
40//! ```rust
41//! use agent_uri::{AgentUriBuilder, TrustRoot, CapabilityPath, AgentId};
42//!
43//! let uri = AgentUriBuilder::new()
44//!     .trust_root(TrustRoot::parse("anthropic.com").unwrap())
45//!     .capability_path(CapabilityPath::parse("assistant/chat").unwrap())
46//!     .agent_id(AgentId::new("llm_chat"))
47//!     .build()
48//!     .unwrap();
49//!
50//! assert_eq!(uri.trust_root().host_str(), "anthropic.com");
51//! ```
52//!
53//! # Length Constraints
54//!
55//! | Component | Max Length |
56//! |-----------|------------|
57//! | Total URI | 512 chars |
58//! | Trust root | 128 chars |
59//! | Capability path | 256 chars |
60//! | Path segments | 32 max count |
61//! | Each segment | 64 chars |
62//! | Agent ID prefix | 63 chars |
63//! | Agent ID suffix | 26 chars (fixed) |
64//!
65//! # Grammar Specification
66//!
67//! This crate implements the ABNF grammar defined in `grammar.abnf` at the crate root.
68//! The grammar follows RFC 5234 (ABNF) and specifies:
69//!
70//! - **URI structure**: `agent://<trust-root>/<capability-path>/<agent-id>[?query][#fragment]`
71//! - **Trust root**: Domain names, IPv4, and IPv6 addresses with optional ports
72//! - **Capability path**: Hierarchical path with 1-32 segments
73//! - **Agent ID**: `TypeID` format with semantic prefix and `UUIDv7` suffix
74//!
75//! See `grammar.abnf` for the complete formal specification.
76
77#![deny(missing_docs)]
78#![deny(clippy::all)]
79#![deny(clippy::pedantic)]
80#![allow(clippy::module_name_repetitions)]
81
82mod agent_id;
83mod agent_prefix;
84mod builder;
85mod capability_path;
86mod constants;
87mod error;
88mod fragment;
89#[cfg(kani)]
90mod kani_impls;
91mod path_segment;
92pub mod prelude;
93mod query;
94mod trust_root;
95mod type_class;
96mod uri;
97
98pub use agent_id::AgentId;
99pub use agent_prefix::AgentPrefix;
100pub use builder::{AgentUriBuilder, Empty, HasCapabilityPath, HasTrustRoot, Ready};
101pub use capability_path::CapabilityPath;
102pub use constants::{
103    AGENT_SUFFIX_LENGTH, MAX_AGENT_ID_LENGTH, MAX_AGENT_PREFIX_LENGTH, MAX_CAPABILITY_PATH_LENGTH,
104    MAX_DNS_DOMAIN_LENGTH, MAX_DNS_LABEL_LENGTH, MAX_PATH_SEGMENTS, MAX_PATH_SEGMENT_LENGTH,
105    MAX_TRUST_ROOT_LENGTH, MAX_URI_LENGTH, SCHEME,
106};
107pub use error::{
108    AgentIdError, AgentPrefixError, BuilderError, CapabilityPathError, FragmentError, ParseError,
109    ParseErrorKind, PathSegmentError, QueryError, TrustRootError,
110};
111pub use fragment::Fragment;
112pub use path_segment::PathSegment;
113pub use query::QueryParams;
114pub use trust_root::{Host, TrustRoot};
115pub use type_class::{ExtensionClass, TypeClass};
116pub use uri::AgentUri;
agent_uri/lib.rs

agent_uri/
lib.rs
