Struct AgentBuilder 

pub struct AgentBuilder { /* private fields */ }

Builder for configuring and creating an agent.

Use Agent::builder() to start building. All methods are optional except llm().

Example

let agent = Agent::builder()
    .llm(Arc::new(provider))
    .tools(registry)
    .system_prompt("You are a helpful assistant")
    .max_steps(50)
    .build()?;

Implementations

impl AgentBuilder

pub fn llm(self, llm: Arc<dyn LlmProvider>) -> Self

Set the LLM provider (required).

The provider handles all requests to the model. Must be provided before calling build(), otherwise build() will return an error.

pub fn tools(self, tools: ToolRegistry) -> Self

Set the tool registry (optional, defaults to empty registry).

Tools are available to the model for execution during the run. If not set, the agent will only generate text. The registry is shared via Arc, so tool implementations must be thread-safe.

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

Set the system prompt (optional).

Prepended to the transcript before the first goal. Typically describes the agent’s role (e.g., “You are a code assistant”). If not set, no system message is added.

pub fn max_steps(self, n: usize) -> Self

Set the maximum number of agent iterations (optional, defaults to 32).

Each iteration is one LLM call + tool execution round. Higher values allow more complex reasoning but increase cost and latency. If exceeded, the run finishes with FinishReason::BudgetExceeded.

pub fn max_transcript_chars(self, n: usize) -> Self

Set the maximum transcript character size (optional).

Prevents the transcript from growing unbounded. When this limit is approached, Compactor (if configured) will summarize and trim old messages. If the transcript cannot fit within the limit, the run stops with FinishReason::TranscriptLimit.

Note

This is a hard limit; if compaction cannot reduce the size enough, the run will terminate rather than add the next message.

pub fn events(self, tx: UnboundedSender<StepEvent>) -> Self

Attach an event channel to observe agent progress (optional).

Events are sent through this channel as the agent runs. Non-blocking: if the receiver is dropped or the channel is full, sends are silently ignored. Allows UI layers to display real-time progress without coupling to the agent’s internals.

pub fn seed_transcript(self, messages: Vec<Message>) -> Self

Seed the agent with a pre-existing transcript. Seeded messages are placed in the transcript after the system prompt but before the new goal. No StepEvents are emitted for seeded messages; only events produced during the new run are streamed.

pub fn streaming(self, enabled: bool) -> Self

Enable token-by-token streaming from the provider (optional, defaults to false).

If enabled, the agent creates a channel and asks the provider to emit PartialToken events as they arrive. Requires provider support; some providers ignore this and emit the complete response at once.

pub fn compactor(self, compactor: Compactor) -> Self

Attach a compactor to automatically trim old transcript content (optional).

When the transcript reaches max_transcript_chars, the compactor summarizes and removes old messages. Only active if both max_transcript_chars and compactor are set. Without a compactor, TranscriptLimit errors occur.

pub fn permission_hook<F>(self, hook: F) -> Self

where F: Fn(&str, &Value) -> PermissionDecision + Send + Sync + 'static,

Attach a permission hook that is invoked before each tool execution (optional).

The hook can allow, deny, or transform tool arguments. If denied, the tool is not executed and the reason is returned as a tool error. If transformed, the new arguments are passed to the tool instead.

pub fn permission_hook_opt(self, hook: Option<PermissionHook>) -> Self

Attach a pre-built permission hook (e.g. cloned from a parent agent).

This is useful when inheriting a permission hook from a parent agent into a sub-agent. Unlike permission_hook(), this accepts an Option<PermissionHook> directly, avoiding the need to re-wrap.

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

Register a lifecycle hook (optional).

Hooks are invoked at well-defined lifecycle points during the agent run. Multiple hooks are supported; they fire in registration order.

pub fn planning_mode(self, mode: PlanningMode) -> Self

Set the planning mode (optional, defaults to Immediate).

When set to PlanFirst, the agent will buffer tool calls and emit a PlanProposed event instead of executing them immediately. The caller must then call confirm_plan() or reject_plan() to proceed.

pub fn build(self) -> Result<Agent>

Trait Implementations

impl Default for AgentBuilder

fn default() -> AgentBuilder

Returns the “default value” for a type.