Struct AgentUriBuilder 

pub struct AgentUriBuilder<State = Empty> { /* private fields */ }

A typestate builder for constructing AgentUri instances.

This builder enforces at compile-time that components are added in the correct order: trust root, then capability path, then agent ID. Query and fragment are optional and can be added at any point.

Type State

The builder uses phantom types to track which components have been set:

• Empty: Initial state, no components set
• HasTrustRoot: Trust root has been set
• HasCapabilityPath: Trust root and capability path have been set
• Ready: All required components set, can call build()

Examples

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");

Compile-Time Safety

Attempting to call methods out of order results in a compile error:

use agent_uri::{AgentUriBuilder, CapabilityPath};

// Error: cannot call capability_path() before trust_root()
let path = CapabilityPath::parse("chat").unwrap();
let builder = AgentUriBuilder::new()
    .capability_path(path);  // Compile error!

use agent_uri::{AgentUriBuilder, TrustRoot};

// Error: cannot call build() without all required components
let root = TrustRoot::parse("example.com").unwrap();
let uri = AgentUriBuilder::new()
    .trust_root(root)
    .build();  // Compile error!

Implementations

impl AgentUriBuilder<Empty>

pub fn new() -> Self

Creates a new builder in the initial state.

Examples

use agent_uri::AgentUriBuilder;

let builder = AgentUriBuilder::new();

pub fn trust_root(self, trust_root: TrustRoot) -> AgentUriBuilder<HasTrustRoot>

Sets the trust root and advances to the HasTrustRoot state.

This must be called first before setting other required components.

Arguments

• trust_root - The validated trust root (authority) for the URI

Examples

use agent_uri::{AgentUriBuilder, TrustRoot};

let builder = AgentUriBuilder::new()
    .trust_root(TrustRoot::parse("anthropic.com").unwrap());

pub fn try_trust_root( self, s: &str, ) -> Result<AgentUriBuilder<HasTrustRoot>, TrustRootError>

Parses and sets the trust root from a string.

This is a convenience method that combines parsing and setting the trust root.

Errors

Returns TrustRootError if the string is not a valid trust root.

Examples

use agent_uri::AgentUriBuilder;

let builder = AgentUriBuilder::new()
    .try_trust_root("anthropic.com")?;

impl AgentUriBuilder<HasTrustRoot>

pub fn capability_path( self, capability_path: CapabilityPath, ) -> AgentUriBuilder<HasCapabilityPath>

Sets the capability path and advances to the HasCapabilityPath state.

This must be called after trust_root() and before agent_id().

Arguments

• capability_path - The validated capability path describing the agent’s function

Examples

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

let builder = AgentUriBuilder::new()
    .trust_root(TrustRoot::parse("anthropic.com").unwrap())
    .capability_path(CapabilityPath::parse("assistant/chat").unwrap());

pub fn try_capability_path( self, s: &str, ) -> Result<AgentUriBuilder<HasCapabilityPath>, CapabilityPathError>

Parses and sets the capability path from a string.

This is a convenience method that combines parsing and setting the capability path.

Errors

Returns CapabilityPathError if the string is not a valid capability path.

Examples

use agent_uri::AgentUriBuilder;

let builder = AgentUriBuilder::new()
    .try_trust_root("anthropic.com")?
    .try_capability_path("assistant/chat")?;

impl AgentUriBuilder<HasCapabilityPath>

pub fn agent_id(self, agent_id: AgentId) -> AgentUriBuilder<Ready>

Sets the agent ID and advances to the Ready state.

After calling this, the builder is ready to call build().

Arguments

• agent_id - The validated agent identifier

Examples

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

let builder = AgentUriBuilder::new()
    .trust_root(TrustRoot::parse("anthropic.com").unwrap())
    .capability_path(CapabilityPath::parse("assistant/chat").unwrap())
    .agent_id(AgentId::new("llm_chat"));
// Builder is now in Ready state and can call build()

pub fn try_agent_id( self, s: &str, ) -> Result<AgentUriBuilder<Ready>, AgentIdError>

Parses and sets the agent ID from a string.

This is a convenience method that combines parsing and setting the agent ID.

Errors

Returns AgentIdError if the string is not a valid agent ID.

Examples

use agent_uri::AgentUriBuilder;

let builder = AgentUriBuilder::new()
    .try_trust_root("anthropic.com")?
    .try_capability_path("assistant/chat")?
    .try_agent_id("llm_chat_01h455vb4pex5vsknk084sn02q")?;

impl AgentUriBuilder<Ready>

pub fn build(self) -> Result<AgentUri, BuilderError>

Builds the final AgentUri.

This method is only available when the builder is in the Ready state, meaning all required components (trust root, capability path, agent ID) have been set.

Errors

Returns BuilderError::UriTooLong if the resulting URI would exceed the maximum allowed length of 512 characters.

Panics

This method will not panic in practice because the typestate pattern guarantees all required fields are set before build() can be called. The internal expect() calls are for defense-in-depth only.

Examples

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");

impl<State> AgentUriBuilder<State>

Methods available in all states after Empty for optional components.

pub fn query(self, query: QueryParams) -> Self

Sets optional query parameters.

This can be called at any point in the builder chain. If called multiple times, the last value wins.

Arguments

• query - The query parameters to include in the URI

Examples

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

let uri = AgentUriBuilder::new()
    .trust_root(TrustRoot::parse("anthropic.com").unwrap())
    .query(QueryParams::parse("version=2.0").unwrap())
    .capability_path(CapabilityPath::parse("chat").unwrap())
    .agent_id(AgentId::new("llm"))
    .build()
    .unwrap();

assert_eq!(uri.query().version(), Some("2.0"));

pub fn fragment(self, fragment: Fragment) -> Self

Sets the optional fragment.

This can be called at any point in the builder chain. If called multiple times, the last value wins.

Arguments

• fragment - The fragment to include in the URI

Examples

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

let uri = AgentUriBuilder::new()
    .trust_root(TrustRoot::parse("anthropic.com").unwrap())
    .capability_path(CapabilityPath::parse("chat").unwrap())
    .fragment(Fragment::parse("summarization").unwrap())
    .agent_id(AgentId::new("llm"))
    .build()
    .unwrap();

assert_eq!(uri.fragment().map(|f| f.as_str()), Some("summarization"));

pub fn try_query(self, s: &str) -> Result<Self, QueryError>

Parses and sets the query parameters from a string.

This is a convenience method that combines parsing and setting query parameters.

Errors

Returns QueryError if the string is not a valid query string.

Examples

use agent_uri::AgentUriBuilder;

let builder = AgentUriBuilder::new()
    .try_query("version=2.0&ttl=300")?;

pub fn try_fragment(self, s: &str) -> Result<Self, FragmentError>

Parses and sets the fragment from a string.

This is a convenience method that combines parsing and setting the fragment.

Errors

Returns FragmentError if the string is not a valid fragment.

Examples

use agent_uri::AgentUriBuilder;

let builder = AgentUriBuilder::new()
    .try_fragment("summarization")?;

pub fn maybe_query(self, query: Option<QueryParams>) -> Self

Sets the query if provided, otherwise leaves it unchanged.

This is useful when the query is optional and may be None.

Examples

use agent_uri::{AgentUriBuilder, QueryParams};

let query = Some(QueryParams::parse("version=2.0").unwrap());
let builder = AgentUriBuilder::new()
    .maybe_query(query);

pub fn maybe_fragment(self, fragment: Option<Fragment>) -> Self

Sets the fragment if provided, otherwise leaves it unchanged.

This is useful when the fragment is optional and may be None.

Examples

use agent_uri::{AgentUriBuilder, Fragment};

let fragment = Some(Fragment::parse("test").unwrap());
let builder = AgentUriBuilder::new()
    .maybe_fragment(fragment);

pub fn maybe_query_str(self, s: Option<&str>) -> Result<Self, QueryError>

Parses and sets the query from a string if provided.

This is useful when the query string is optional and may be None.

Errors

Returns QueryError if the provided string is not a valid query string.

Examples

use agent_uri::AgentUriBuilder;

let query_str = Some("version=2.0");
let builder = AgentUriBuilder::new()
    .maybe_query_str(query_str)?;

pub fn maybe_fragment_str(self, s: Option<&str>) -> Result<Self, FragmentError>

Parses and sets the fragment from a string if provided.

This is useful when the fragment string is optional and may be None.

Errors

Returns FragmentError if the provided string is not a valid fragment.

Examples

use agent_uri::AgentUriBuilder;

let fragment_str = Some("summarization");
let builder = AgentUriBuilder::new()
    .maybe_fragment_str(fragment_str)?;

Trait Implementations

impl<State: Clone> Clone for AgentUriBuilder<State>

fn clone(&self) -> AgentUriBuilder<State>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<State: Debug> Debug for AgentUriBuilder<State>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AgentUriBuilder<Empty>

fn default() -> Self

Returns the “default value” for a type.