Struct Agent 

pub struct Agent { /* private fields */ }

The agent loop.

match agent.run("What is the weather in Chicago?").await? {
    AgentOutcome::Completed { text, .. } => println!("answer: {text}"),
    other => println!("stopped: {other:?}"),
}

Implementations

impl Agent

pub fn new(client: Arc<dyn LlmClient>) -> Self

Start building an agent around a provider client.

pub fn tools(self, tools: Vec<Arc<dyn Tool>>) -> Self

Tools the model may call. Replaces any earlier list.

pub fn tool(self, tool: Arc<dyn Tool>) -> Self

Add one tool to the list.

pub fn system_prompt(self, prompt: impl Into<String>) -> Self

System prompt prepended to every run.

pub const fn max_steps(self, max_steps: u32) -> Self

Maximum tool-execution rounds before the run stops with BudgetKind::Steps.

A step is one round in which the model requested tool calls; the final answering call does not consume a step.

pub const fn max_tokens(self, max_tokens: u32) -> Self

Token budget for the whole run (estimated + provider-reported).

pub const fn max_duration(self, limit: Duration) -> Self

Wall-clock limit for one run (or one resume). Model and tool calls still in flight at the deadline are cancelled; the run ends with BudgetKind::Deadline.

pub const fn per_tool_output_limit(self, limit: usize) -> Self

Truncate any single tool output to this many characters.

One chatty tool must not eat the whole context window.

pub const fn temperature(self, temperature: f32) -> Self

Sampling temperature for model calls.

pub fn hook(self, hook: Arc<dyn AgentHooks>) -> Self

Add a lifecycle hook. Hooks run in the order they were added.

pub fn policy(self, policy: Arc<dyn ToolPolicy>) -> Self

Decide per call whether the agent may act. Defaults to AllowAll.

pub const fn loop_guard(self, guard: LoopGuard) -> Self

Loop-detection thresholds. Use LoopGuard::disabled to turn it off.

pub const fn parallel_tool_calls(self, parallel: bool) -> Self

Run the calls of one round concurrently (the default) or one by one.

pub fn memory(self, store: Arc<dyn MemoryStore>, scope: MemoryScope) -> Self

Give the agent persistent memory: a frozen snapshot in the system prompt plus the memory tool, both bound to scope.

pub fn skills(self, skills: impl Into<Arc<[Skill]>>) -> Self

Offer skills: an index in the system prompt plus the load_skill tool.

pub const fn compaction(self, compaction: Compaction) -> Self

Summarize long session transcripts before a run. Applies to Agent::run_in_session.

pub fn run_id(self, run_id: RunId) -> Self

Use this id for the next run instead of generating one. Background jobs set it so a retried job keeps the same run id.

pub async fn run(&self, user_input: &str) -> Result<AgentOutcome, AgentError>

Run the agent loop against one user message, with no prior history.

Errors

Returns AgentError when a provider call fails (transport, auth, rate limit, malformed response) or memory cannot load. Budget exhaustion, loops, and approval pauses are not errors: they come back as AgentOutcome variants.

pub async fn run_turn( &self, history: Vec<ChatMessage>, user_input: &str, ) -> Result<AgentTurn, AgentError>

Continue a transcript with one user message.

history is a transcript from an earlier AgentTurn::messages (no system messages needed: the agent adds its own).

Errors

See Agent::run.

pub async fn run_in_session( &self, store: &dyn SessionStore, session_id: &SessionId, user_input: &str, ) -> Result<AgentTurn, AgentError>

Run one turn inside a persisted session.

Loads the transcript, compacts it when Agent::compaction is set and the transcript is long, runs, then saves the new transcript. A run that pauses for approval saves nothing: Agent::resume_in_session saves once the run finishes. A new message sent to the session while a run waits for approval continues from the last saved transcript.

Errors

See Agent::run; also fails when the store or the compaction call fails.

pub async fn resume( &self, state: RunState, decisions: Vec<ApprovalDecision>, ) -> Result<AgentTurn, AgentError>

Continue a run that paused with AgentOutcome::AwaitingApproval.

Calls the policy allowed run; calls it denied report their reason; calls that needed approval follow decisions — a call with no decision counts as rejected. The deadline restarts on resume.

Errors

Returns ErrorKind::Config when a decision names a call that is not waiting for approval, plus every error of Agent::run.

pub async fn resume_in_session( &self, store: &dyn SessionStore, state: RunState, decisions: Vec<ApprovalDecision>, ) -> Result<AgentTurn, AgentError>

Agent::resume, then save the transcript to the run’s session.

Errors

See Agent::resume; also fails when the store fails.

Trait Implementations

impl Clone for Agent

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 Agent

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

Formats the value using the given formatter.