Struct AgentBuilder 

pub struct AgentBuilder<M, P = (), ToolState = NoToolConfig>
where
    M: CompletionModel,
    P: PromptHook<M>,
{ /* private fields */ }

A builder for creating an agent

The builder uses a typestate pattern to enforce that tool configuration is done in a mutually exclusive way: either provide a pre-existing ToolServerHandle, or add tools via the builder API, but not both.

Example

use rig::{providers::openai, agent::AgentBuilder};

let openai = openai::Client::from_env();

let gpt4o = openai.completion_model("gpt-4o");

// Configure the agent
let agent = AgentBuilder::new(gpt4o)
    .preamble("System prompt")
    .context("Context document 1")
    .context("Context document 2")
    .tool(tool1)
    .tool(tool2)
    .temperature(0.8)
    .additional_params(json!({"foo": "bar"}))
    .build();

Implementations

impl<M, P, ToolState> AgentBuilder<M, P, ToolState>

where M: CompletionModel, P: PromptHook<M>,

pub fn name(self, name: &str) -> AgentBuilder<M, P, ToolState>

Set the name of the agent

pub fn description(self, description: &str) -> AgentBuilder<M, P, ToolState>

Set the description of the agent

pub fn preamble(self, preamble: &str) -> AgentBuilder<M, P, ToolState>

Set the system prompt

pub fn without_preamble(self) -> AgentBuilder<M, P, ToolState>

Remove the system prompt

pub fn append_preamble(self, doc: &str) -> AgentBuilder<M, P, ToolState>

Append to the preamble of the agent

pub fn context(self, doc: &str) -> AgentBuilder<M, P, ToolState>

Add a static context document to the agent

pub fn dynamic_context( self, sample: usize, dynamic_context: impl VectorStoreIndexDyn + Send + Sync + 'static, ) -> AgentBuilder<M, P, ToolState>

Add some dynamic context to the agent. On each prompt, sample documents from the dynamic context will be inserted in the request.

pub fn tool_choice( self, tool_choice: ToolChoice, ) -> AgentBuilder<M, P, ToolState>

Set the tool choice for the agent

pub fn default_max_turns( self, default_max_turns: usize, ) -> AgentBuilder<M, P, ToolState>

Set the default maximum depth that an agent will use for multi-turn.

pub fn temperature(self, temperature: f64) -> AgentBuilder<M, P, ToolState>

Set the temperature of the model

pub fn max_tokens(self, max_tokens: u64) -> AgentBuilder<M, P, ToolState>

Set the maximum number of tokens for the completion

pub fn additional_params(self, params: Value) -> AgentBuilder<M, P, ToolState>

Set additional parameters to be passed to the model

pub fn output_schema<T>(self) -> AgentBuilder<M, P, ToolState>

where T: JsonSchema,

Set the output schema for structured output. When set, providers that support native structured outputs will constrain the model’s response to match this schema.

pub fn output_schema_raw(self, schema: Schema) -> AgentBuilder<M, P, ToolState>

Set the output schema for structured output. In comparison to AgentBuilder::schema() which requires type annotation, you can put in any schema you’d like here.

impl<M> AgentBuilder<M>

where M: CompletionModel,

pub fn new(model: M) -> AgentBuilder<M>

Create a new agent builder with the given model

impl<M, P> AgentBuilder<M, P>

where M: CompletionModel, P: PromptHook<M>,

pub fn tool_server_handle( self, handle: ToolServerHandle, ) -> AgentBuilder<M, P, WithToolServerHandle>

Set a pre-existing ToolServerHandle for the agent.

After calling this method, tool-adding methods (.tool(), .tools(), etc.) will not be available. Use this when you want to share a ToolServer between multiple agents or have pre-configured tools.

pub fn tool( self, tool: impl Tool + 'static, ) -> AgentBuilder<M, P, WithBuilderTools>

Add a static tool to the agent.

This transitions the builder to the WithBuilderTools state, where additional tools can be added but tool_server_handle() is no longer available.

pub fn tools( self, tools: Vec<Box<dyn ToolDyn>>, ) -> AgentBuilder<M, P, WithBuilderTools>

Add a vector of boxed static tools to the agent.

This is useful when you need to dynamically add static tools to the agent. Transitions the builder to the WithBuilderTools state.

pub fn dynamic_tools( self, sample: usize, dynamic_tools: impl VectorStoreIndexDyn + Send + Sync + 'static, toolset: ToolSet, ) -> AgentBuilder<M, P, WithBuilderTools>

Add some dynamic tools to the agent. On each prompt, sample tools from the dynamic toolset will be inserted in the request.

Transitions the builder to the WithBuilderTools state.

pub fn hook<P2>(self, hook: P2) -> AgentBuilder<M, P2>

where P2: PromptHook<M>,

Set the default hook for the agent.

This hook will be used for all prompt requests unless overridden via .with_hook() on the request.

pub fn build(self) -> Agent<M, P>

Build the agent with no tools configured.

An empty ToolServer will be created for the agent.

impl<M, P> AgentBuilder<M, P, WithToolServerHandle>

where M: CompletionModel, P: PromptHook<M>,

pub fn build(self) -> Agent<M, P>

Build the agent using the pre-configured ToolServerHandle.

impl<M, P> AgentBuilder<M, P, WithBuilderTools>

where M: CompletionModel, P: PromptHook<M>,

pub fn tool( self, tool: impl Tool + 'static, ) -> AgentBuilder<M, P, WithBuilderTools>

Add another static tool to the agent.

pub fn tools( self, tools: Vec<Box<dyn ToolDyn>>, ) -> AgentBuilder<M, P, WithBuilderTools>

Add a vector of boxed static tools to the agent.

pub fn dynamic_tools( self, sample: usize, dynamic_tools: impl VectorStoreIndexDyn + Send + Sync + 'static, toolset: ToolSet, ) -> AgentBuilder<M, P, WithBuilderTools>

Add some dynamic tools to the agent. On each prompt, sample tools from the dynamic toolset will be inserted in the request.

pub fn build(self) -> Agent<M, P>

Build the agent with the configured tools.

A new ToolServer will be created containing all tools added via .tool(), .tools(), .dynamic_tools(), etc.