Struct AgentUri

Source

pub struct AgentUri { /* private fields */ }

Expand description

A parsed and validated agent URI.

Agent URIs provide topology-independent identity for agents with capability-based discovery.

§Structure

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

§Examples

use agent_uri::AgentUri;

let uri = AgentUri::parse("agent://anthropic.com/assistant/chat/llm_chat_01h455vb4pex5vsknk084sn02q").unwrap();
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");

// With query and fragment
let uri = AgentUri::parse("agent://openai.com/tool/code/llm_01h455vb4pex5vsknk084sn02q?version=2.0#summarization").unwrap();
assert_eq!(uri.query().version(), Some("2.0"));
assert_eq!(uri.fragment().map(|f| f.as_str()), Some("summarization"));

Implementations§

Source §

impl AgentUri

Source

pub fn parse(input: &str) -> Result<Self, ParseError>

Parses an agent URI from a string.

§Errors

Returns ParseError if:

The URI is empty
The URI exceeds 512 characters
The scheme is not “agent://”
Any component (trust root, path, agent ID, query, fragment) is invalid

Source

pub fn new( trust_root: TrustRoot, capability_path: CapabilityPath, agent_id: AgentId, query: QueryParams, fragment: Option<Fragment>, ) -> Result<Self, ParseError>

Creates a new agent URI from its components.

§Errors

Returns ParseError if the resulting URI would exceed the maximum length.

Source

pub const fn trust_root(&self) -> &TrustRoot

Returns the trust root.

Source

pub const fn capability_path(&self) -> &CapabilityPath

Returns the capability path.

Source

pub const fn agent_id(&self) -> &AgentId

Returns the agent ID.

Source

pub const fn query(&self) -> &QueryParams

Returns the query parameters.

Source

pub const fn fragment(&self) -> Option<&Fragment>

Returns the fragment, if present.

Source

pub fn as_str(&self) -> &str

Returns the normalized URI string.

Source

pub fn canonical(&self) -> String

Returns the canonical URI (without query and fragment).

Source

pub fn is_localhost(&self) -> bool

Returns true if this URI references a localhost agent.

Source

pub fn with_query(&self, query: QueryParams) -> Result<Self, ParseError>

Returns a new URI with the given query parameters.

§Errors

Returns ParseError if the resulting URI would exceed the maximum length.

§Examples

use agent_uri::{AgentUri, QueryParams};

let uri = AgentUri::parse("agent://anthropic.com/chat/llm_01h455vb4pex5vsknk084sn02q").unwrap();
let query = QueryParams::parse("version=2.0").unwrap();
let updated = uri.with_query(query).unwrap();
assert_eq!(updated.query().version(), Some("2.0"));

Source

pub fn with_query_str(&self, s: &str) -> Result<Self, ParseError>

Returns a new URI with query parameters parsed from a string.

§Errors

Returns ParseError if the query string is invalid or the resulting URI would exceed the maximum length.

§Examples

use agent_uri::AgentUri;

let uri = AgentUri::parse("agent://anthropic.com/chat/llm_01h455vb4pex5vsknk084sn02q").unwrap();
let updated = uri.with_query_str("version=2.0&ttl=300").unwrap();
assert_eq!(updated.query().version(), Some("2.0"));
assert_eq!(updated.query().ttl(), Some(300));

Source

pub fn without_query(&self) -> Result<Self, ParseError>

Returns a new URI without query parameters.

§Errors

Returns ParseError if the resulting URI would exceed the maximum length. (This is unlikely but possible in edge cases.)

§Examples

use agent_uri::AgentUri;

let uri = AgentUri::parse("agent://anthropic.com/chat/llm_01h455vb4pex5vsknk084sn02q?version=2.0").unwrap();
let updated = uri.without_query().unwrap();
assert!(updated.query().is_empty());

Source

pub fn with_fragment(&self, fragment: Fragment) -> Result<Self, ParseError>

Returns a new URI with the given fragment.

§Errors

Returns ParseError if the resulting URI would exceed the maximum length.

§Examples

use agent_uri::{AgentUri, Fragment};

let uri = AgentUri::parse("agent://anthropic.com/chat/llm_01h455vb4pex5vsknk084sn02q").unwrap();
let fragment = Fragment::parse("summarization").unwrap();
let updated = uri.with_fragment(fragment).unwrap();
assert_eq!(updated.fragment().map(|f| f.as_str()), Some("summarization"));

Source

pub fn with_fragment_str(&self, s: &str) -> Result<Self, ParseError>

Returns a new URI with a fragment parsed from a string.

§Errors

Returns ParseError if the fragment is invalid or the resulting URI would exceed the maximum length.

§Examples

use agent_uri::AgentUri;

let uri = AgentUri::parse("agent://anthropic.com/chat/llm_01h455vb4pex5vsknk084sn02q").unwrap();
let updated = uri.with_fragment_str("summarization").unwrap();
assert_eq!(updated.fragment().map(|f| f.as_str()), Some("summarization"));

Source

pub fn without_fragment(&self) -> Result<Self, ParseError>

Returns a new URI without a fragment.

§Errors

Returns ParseError if the resulting URI would exceed the maximum length. (This is unlikely but possible in edge cases.)

§Examples

use agent_uri::AgentUri;

let uri = AgentUri::parse("agent://anthropic.com/chat/llm_01h455vb4pex5vsknk084sn02q#test").unwrap();
let updated = uri.without_fragment().unwrap();
assert!(updated.fragment().is_none());