Crate agent_uri 

Parser and validator for the agent:// URI scheme.

This crate implements parsing, validation, and serialization of agent URIs as defined in the Agent Identity URI Scheme specification.

Overview

Agent URIs provide topology-independent identity for agents with capability-based discovery. They have the structure:

agent://<trust-root>/<capability-path>/<agent-id>[?query][#fragment]

Quick Start

use agent_uri::AgentUri;

// Parse an agent URI
let uri = AgentUri::parse(
    "agent://anthropic.com/assistant/chat/llm_chat_01h455vb4pex5vsknk084sn02q"
).unwrap();

// Access components
assert_eq!(uri.trust_root().host_str(), "anthropic.com");
assert_eq!(uri.capability_path().as_str(), "assistant/chat");
assert_eq!(uri.agent_id().prefix().as_str(), "llm_chat");

// Create new agent IDs
use agent_uri::AgentId;
let id = AgentId::new("llm_chat");
println!("New agent: {}", id);

Builder Pattern

Use the typestate builder for compile-time enforced construction:

use agent_uri::{AgentUriBuilder, TrustRoot, CapabilityPath, AgentId};

let uri = AgentUriBuilder::new()
    .trust_root(TrustRoot::parse("anthropic.com").unwrap())
    .capability_path(CapabilityPath::parse("assistant/chat").unwrap())
    .agent_id(AgentId::new("llm_chat"))
    .build()
    .unwrap();

assert_eq!(uri.trust_root().host_str(), "anthropic.com");

Length Constraints

Component	Max Length
Total URI	512 chars
Trust root	128 chars
Capability path	256 chars
Path segments	32 max count
Each segment	64 chars
Agent ID prefix	63 chars
Agent ID suffix	26 chars (fixed)

Grammar Specification

This crate implements the ABNF grammar defined in grammar.abnf at the crate root. The grammar follows RFC 5234 (ABNF) and specifies:

• URI structure: agent://<trust-root>/<capability-path>/<agent-id>[?query][#fragment]
• Trust root: Domain names, IPv4, and IPv6 addresses with optional ports
• Capability path: Hierarchical path with 1-32 segments
• Agent ID: TypeID format with semantic prefix and UUIDv7 suffix

See grammar.abnf for the complete formal specification.

Modules

prelude

Convenient re-exports for glob imports.

Structs

AgentId

A validated agent identifier in TypeID format.

AgentPrefix

A validated agent prefix (semantic type classification).

AgentUri

A parsed and validated agent URI.

AgentUriBuilder

A typestate builder for constructing AgentUri instances.

CapabilityPath

A validated capability path from an agent URI.

Empty

Marker: No components set yet.

ExtensionClass

An extension class name (custom type classes).

Fragment

A validated fragment from an agent URI.

HasCapabilityPath

Marker: Trust root and capability path have been set.

HasTrustRoot

Marker: Trust root has been set.

ParseError

Errors that can occur when parsing an agent URI.

PathSegment

A validated path segment in a capability path.

QueryParams

Query parameters from an agent URI.

Ready

Marker: All required components are set, ready to build.

TrustRoot

A validated trust root (authority) from an agent URI.

Enums

AgentIdError

Errors for agent ID parsing.

AgentPrefixError

Errors for agent prefix parsing.

BuilderError

Errors that can occur when building an agent URI.

CapabilityPathError

Errors for capability path parsing.

FragmentError

Errors for fragment parsing.

Host

The host portion of a trust root.

ParseErrorKind

Specific parsing error types.

PathSegmentError

Errors for path segment parsing.

QueryError

Errors for query string parsing.

TrustRootError

Errors for trust root parsing.

TypeClass

Primary type classification for agents.

Constants

AGENT_SUFFIX_LENGTH

Fixed agent-id suffix length (UUIDv7 in base32).

MAX_AGENT_ID_LENGTH

Maximum total agent-id length (prefix + underscore + suffix).

MAX_AGENT_PREFIX_LENGTH

Maximum agent-id prefix length per TypeID spec.

MAX_CAPABILITY_PATH_LENGTH

Maximum capability path length (all segments combined with slashes).

MAX_DNS_DOMAIN_LENGTH

DNS domain maximum length.

MAX_DNS_LABEL_LENGTH

DNS label maximum length.

MAX_PATH_SEGMENTS

Maximum number of path segments.

MAX_PATH_SEGMENT_LENGTH

Maximum length of a single path segment.

MAX_TRUST_ROOT_LENGTH

Maximum trust root length including port.

MAX_URI_LENGTH

Maximum total URI length in characters.

SCHEME

The URI scheme.