Struct AgentId 

pub struct AgentId { /* private fields */ }

A validated agent identifier in TypeID format.

The agent ID uniquely identifies an agent and encodes:

• Semantic classification (the prefix)
• Unique identity (the UUIDv7 suffix)
• Creation timestamp (encoded in UUIDv7)

Format

<prefix>_<suffix> where:

• prefix: 1-63 lowercase letters and underscores
• suffix: 26 character base32-encoded UUIDv7

Examples

use agent_uri::AgentId;

let id = AgentId::parse("llm_01h455vb4pex5vsknk084sn02q").unwrap();
assert_eq!(id.prefix().as_str(), "llm");
assert_eq!(id.suffix(), "01h455vb4pex5vsknk084sn02q");

// Create a new agent ID
let id = AgentId::new("llm_chat");
assert_eq!(id.suffix().len(), 26);

Constructing one

AgentId::parse reads an existing ID. The other two mint a fresh one and differ only in what they do with a prefix the grammar rejects: AgentId::new rewrites it, AgentId::try_new reports it. Prefer try_new for any prefix that did not come from your own source.

Implementations

impl AgentId

pub fn new(prefix: &str) -> Self

Creates a new agent ID with the given prefix and a fresh UUIDv7, sanitizing the prefix if the grammar does not already accept it.

This is the split mti draws, and this crate mints TypeIDs with mti: create_type_id sanitizes and try_create_type_id refuses. Sanitizing is described on AgentId::try_new’s counterpart below; in short, anything outside [a-z_] is dropped, uppercase is folded, and a prefix left with nothing becomes agent.

Choosing between this and AgentId::try_new

Sanitizing means you get an agent ID with a prefix, not necessarily the one you named. That is what you want when the prefix is a label you wrote: minting an ID should not be fallible over a string literal. It is not what you want when the prefix arrived from somewhere — a peer, a config file, a URI — because a rewritten prefix is a different agent class than the one that was asked for, and silence about that is how a caller ends up registering under a name it never chose. Untrusted input belongs in AgentId::try_new or AgentId::parse, which refuse.

Examples

use agent_uri::AgentId;

// A prefix the grammar already accepts is kept verbatim.
let id = AgentId::new("llm_chat");
assert_eq!(id.prefix().as_str(), "llm_chat");

// Anything else is rewritten rather than refused.
assert_eq!(AgentId::new("LLM Chat!").prefix().as_str(), "llmchat");
assert_eq!(AgentId::new("__llm__chat__").prefix().as_str(), "llm_chat");
assert_eq!(AgentId::new("123").prefix().as_str(), "agent");

// Every one of them is a parsable agent ID.
assert!(AgentId::parse(&AgentId::new("123").to_string()).is_ok());

pub fn try_new(prefix: &str) -> Result<Self, AgentIdError>

Creates a new agent ID with the given prefix and a fresh UUIDv7, refusing a prefix the grammar does not accept.

Use this whenever the prefix came from outside your own source: it reports what AgentId::new would have quietly rewritten.

Errors

Returns AgentIdError if the prefix is invalid.

Examples

use agent_uri::AgentId;

assert!(AgentId::try_new("llm_chat").is_ok());
assert!(AgentId::try_new("LLM Chat!").is_err());

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

Parses an agent ID from a string.

Errors

Returns AgentIdError if:

• The input is empty
• The input exceeds 90 characters
• The prefix is invalid
• The suffix is invalid (not valid base32 or wrong length)
• The separator is missing

pub const fn prefix(&self) -> &AgentPrefix

Returns the prefix (semantic classification).

pub fn suffix(&self) -> &str

Returns the suffix (base32-encoded UUIDv7).

pub const fn inner(&self) -> &MagicTypeId

Returns the underlying MagicTypeId.

pub fn uuid(&self) -> Result<Uuid, AgentIdError>

Returns the UUID from the suffix.

Errors

Returns an error if UUID extraction fails.

Trait Implementations

impl AsRef<MagicTypeId> for AgentId

fn as_ref(&self) -> &MagicTypeId

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for AgentId

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AgentId

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for AgentId

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for AgentId

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

Formats the value using the given formatter.

impl Eq for AgentId

impl FromStr for AgentId

type Err = AgentIdError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for AgentId

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for AgentId

Orders by the rendered prefix_suffix, which is what Display writes.

The comparison is the one this always made; what is gone is the pair of Strings it used to build to make it. MagicTypeId keeps its own rendering and hands out a borrow of it, so nothing has to be rendered again here. MagicTypeId’s own Ord is not that comparison — it sorts by suffix first, which would order agents by creation time rather than by class.

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for AgentId

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for AgentId

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for AgentId

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for AgentId

impl TryFrom<&str> for AgentId

type Error = AgentIdError

The type returned in the event of a conversion error.

fn try_from(s: &str) -> Result<Self, Self::Error>

Performs the conversion.