Struct AgentBuilder 

pub struct AgentBuilder<M, ToolState = NoToolConfig>
where
    M: CompletionModel,
{ /* 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_core::{agent::AgentBuilder, client::{CompletionClient, ProviderClient}, providers::openai};

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

let model = openai.completion_model(openai::GPT_5_2);

// Configure the agent
let agent = AgentBuilder::new(model)
    .preamble("System prompt")
    .context("Context document 1")
    .context("Context document 2")
    .temperature(0.8)
    .build();

Implementations

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

where M: CompletionModel,

pub fn name(self, name: &str) -> Self

Set the name of the agent

pub fn description(self, description: &str) -> Self

Set the description of the agent

pub fn preamble(self, preamble: &str) -> Self

Set the system prompt

pub fn without_preamble(self) -> Self

Remove the system prompt

pub fn append_preamble(self, doc: &str) -> Self

Append to the preamble of the agent

pub fn context(self, doc: &str) -> Self

Add a static context document to the agent

pub fn dynamic_context( self, sample: usize, dynamic_context: impl VectorStoreIndexDyn + Send + Sync + 'static, ) -> Self

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) -> Self

Set the tool choice for the agent

pub fn default_max_turns(self, default_max_turns: usize) -> Self

Set the default total model-call budget, including the initial call and every retry or continuation. Zero permits no model calls.

pub fn temperature(self, temperature: f64) -> Self

Set the temperature of the model

pub fn max_tokens(self, max_tokens: u64) -> Self

Set the maximum number of tokens for the completion

pub fn additional_params(self, params: Value) -> Self

Set additional parameters to be passed to the model

pub fn output_schema<T>(self) -> Self

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) -> Self

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.

pub fn output_mode(self, mode: OutputMode) -> Self

Set how output_schema is enforced — OutputMode::Tool (output as a tool call, the default when the agent has tools), OutputMode::Native (provider structured output), or OutputMode::Prompted (see #1928). Has no effect unless output_schema/output_schema_raw is also set.

pub fn memory<B>(self, memory: B) -> Self

where B: ConversationMemory + 'static,

Attach a ConversationMemory backend.

When set, the agent will automatically load prior conversation history before each prompt and append the new turn after a successful response. A conversation_id must be supplied either via AgentBuilder::conversation or per-request via crate::agent::prompt_request::PromptRequest::conversation. If neither is set, memory is silently bypassed.

pub fn conversation(self, id: impl Into<String>) -> Self

Set a default conversation id used when none is provided per-request.

Most agents are reused across users or threads; prefer setting the id per-request via crate::agent::prompt_request::PromptRequest::conversation.

pub fn add_hook<H>(self, hook: H) -> Self

where H: AgentHook<M> + 'static,

Attach a default hook to the agent. Each call appends to the agent’s hook stack; hooks run for every prompt request (unless more are added per request) in registration order. How their results compose is event-dependent: CompletionCall request patches accumulate and merge, ToolCall/ToolResult rewrites chain, and only observe-only/recovery events use first-non-Continue-wins. See the hook module docs.

impl<M> AgentBuilder<M, NoToolConfig>

where M: CompletionModel,

pub fn new(model: M) -> Self

Create a new agent builder with the given model

impl<M> AgentBuilder<M, NoToolConfig>

where M: CompletionModel,

pub fn tool_server_handle( self, handle: ToolServerHandle, ) -> AgentBuilder<M, 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, 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, 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 rmcp_tool( self, tool: Tool, client: ServerSink, ) -> AgentBuilder<M, WithBuilderTools>

Available on crate feature rmcp only.

Add an MCP tool (from rmcp) to the agent, bounded by DEFAULT_MCP_TOOL_TIMEOUT (see issue #1914). Use rmcp_tool_with_timeout to change or disable it.

Transitions the builder to the WithBuilderTools state.

pub fn rmcp_tool_with_timeout( self, tool: Tool, client: ServerSink, timeout: impl Into<Option<Duration>>, ) -> AgentBuilder<M, WithBuilderTools>

Available on crate feature rmcp only.

Add an MCP tool (from rmcp) with a per-call timeout (see issue #1914).

Pass a Duration to bound the call, or None to disable the timeout (unbounded). On timeout the call resolves to a tool error the agent can recover from instead of blocking forever. Transitions the builder to the WithBuilderTools state.

pub fn rmcp_tools( self, tools: Vec<Tool>, client: ServerSink, ) -> AgentBuilder<M, WithBuilderTools>

Available on crate feature rmcp only.

Add an array of MCP tools (from rmcp) to the agent, each bounded by DEFAULT_MCP_TOOL_TIMEOUT (see issue #1914). Use rmcp_tools_with_timeout to change or disable it.

Transitions the builder to the WithBuilderTools state.

pub fn rmcp_tools_with_timeout( self, tools: Vec<Tool>, client: ServerSink, timeout: impl Into<Option<Duration>>, ) -> AgentBuilder<M, WithBuilderTools>

Available on crate feature rmcp only.

Add an array of MCP tools (from rmcp) with a per-call timeout (see issue #1914).

Pass a Duration to bound calls, or None to disable the timeout (unbounded). On timeout a call resolves to a tool error the agent can recover from instead of blocking forever. 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, 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 build(self) -> Agent<M>

Build the agent with no tools configured.

An empty ToolServer will be created for the agent.

impl<M> AgentBuilder<M, WithToolServerHandle>

where M: CompletionModel,

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

Build the agent using the pre-configured ToolServerHandle.

impl<M> AgentBuilder<M, WithBuilderTools>

where M: CompletionModel,

pub fn tool(self, tool: impl Tool + 'static) -> Self

Add another static tool to the agent.

pub fn tools(self, tools: Vec<Box<dyn ToolDyn>>) -> Self

Add a vector of boxed static tools to the agent.

pub fn rmcp_tools(self, tools: Vec<Tool>, client: ServerSink) -> Self

Available on crate feature rmcp only.

Add an array of MCP tools (from rmcp) to the agent, each bounded by DEFAULT_MCP_TOOL_TIMEOUT (see issue #1914). Use rmcp_tools_with_timeout to change or disable it.

pub fn rmcp_tools_with_timeout( self, tools: Vec<Tool>, client: ServerSink, timeout: impl Into<Option<Duration>>, ) -> Self

Available on crate feature rmcp only.

Add an array of MCP tools (from rmcp) with a per-call timeout (see issue #1914).

Pass a Duration to bound calls, or None to disable the timeout (unbounded). On timeout a call resolves to a tool error the agent can recover from instead of blocking forever.

pub fn dynamic_tools( self, sample: usize, dynamic_tools: impl VectorStoreIndexDyn + Send + Sync + 'static, toolset: ToolSet, ) -> Self

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>

Build the agent with the configured tools.

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