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_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, P, ToolState> AgentBuilder<M, P, ToolState>

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

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 maximum depth that an agent will use for multi-turn.

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 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_id or per-request via crate::agent::prompt_request::PromptRequest::conversation. If neither is set, memory is silently bypassed.

pub fn conversation_id(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.

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, P> AgentBuilder<M, P, NoToolConfig>

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 rmcp_tool( self, tool: Tool, client: ServerSink, ) -> AgentBuilder<M, P, WithBuilderTools>

Available on crate feature rmcp only.

Add an MCP tool (from rmcp) to the agent.

Transitions the builder to the WithBuilderTools state.

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

Available on crate feature rmcp only.

Add an array of MCP tools (from rmcp) 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, NoToolConfig>

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

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, P>

Build the agent with the configured tools.

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