Struct Agent 

pub struct Agent { /* private fields */ }

The main agent struct.

An agent combines an LLM provider, tools, memory, and steering into a single runtime that processes user input and produces output.

Use Agent::builder() to construct an agent.

Implementations

impl Agent

pub fn builder() -> AgentBuilder

Create a builder for constructing an agent.

pub fn with_system(provider: impl Provider, system: impl Into<String>) -> Self

Create an agent with just a provider and system prompt.

This is a convenience shorthand equivalent to:

Agent::builder()
    .provider(provider)
    .system(system)
    .build()
    .unwrap()

All other settings use their defaults (in-memory memory, no tools, no guards, etc.). Use Agent::builder() for full customization.

Example

use traitclaw_core::prelude::*;

let agent = Agent::with_system(provider, "You are a helpful assistant.");

Panics

This method cannot panic under normal usage — the internal build() call only fails when no provider is set, and with_system always provides one.

pub fn session(&self, id: impl Into<String>) -> AgentSession<'_>

Create a session bound to a specific session ID.

The returned AgentSession routes all memory operations through this session ID, providing conversation isolation.

let session = agent.session("user-123");
let output = session.say("Hello!").await?;

pub fn session_auto(&self) -> AgentSession<'_>

Create a session with an auto-generated UUID v4 session ID.

Useful when you want isolated conversations without managing IDs.

pub fn memory(&self) -> &dyn Memory

Returns a reference to the agent’s memory store.

Useful for inspecting conversation history in tests or building custom conversation management on top of the agent.

pub async fn run(&self, input: &str) -> Result<AgentOutput>

Run the agent with user input and return the final output.

This uses the "default" session for backward compatibility. For session isolation, use Agent::session() or Agent::session_auto().

Errors

Returns an error if the provider fails, tool execution fails, memory operations fail, or max iterations are reached.

pub fn stream( &self, input: &str, ) -> Pin<Box<dyn Stream<Item = Result<StreamEvent>> + Send>>

Run the agent and return a streaming response.

This uses the "default" session for backward compatibility.

Returns an AgentStream that yields StreamEvents incrementally, providing real-time output from the LLM.

pub async fn run_structured<T>(&self, input: &str) -> Result<T>

where T: DeserializeOwned + JsonSchema,

Run the agent and return a structured output.

The LLM is instructed to return JSON matching type T’s schema. If deserialization fails, retries up to 3 times with feedback.

When the provider’s model supports native structured-output (model_info.supports_structured == true), the response_format is set on the CompletionRequest for guaranteed valid JSON. Otherwise, schema instructions are injected into the system prompt.

⚠️ Stateless Mode

This method calls the provider directly, bypassing the agent runtime loop. Memory, guards, hints, context strategy, and usage tracking are not used. Use run() for full agent behavior.

Errors

Returns an error if the provider fails or deserialization fails after retries.

Trait Implementations

impl Debug for Agent

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

Formats the value using the given formatter.