Skip to main content

AgentBuilder

Struct AgentBuilder 

Source
pub struct AgentBuilder { /* private fields */ }
Expand description

Builds an Agent.

Every handler the builder registers (the default model, model routes, dynamic-context indexes) is minted a key under the agent’s owner label at build: <owner>/model:<label> and <owner>/retrieve:context#<n>. Hosts sharing a table must choose distinct owners to avoid replacing each other’s bindings. The explicit owner takes precedence over the agent name, then a generated agent#<n> label.

Implementations§

Source§

impl AgentBuilder

Source

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

Name the agent.

Source

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

Describe the agent.

Source

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

Set the system prompt.

Source

pub fn without_preamble(self) -> Self

Clear the system prompt.

Source

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

Append a paragraph to the system prompt.

Source

pub fn context(self, doc: impl Into<String>) -> Self

Add a static context document.

Source

pub fn dynamic_context<I, F>(self, samples: usize, index: I) -> Self
where I: VectorStoreIndex<Filter = F> + 'static, F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,

Retrieve samples documents from index for every prompt and add them as context. The index is registered in the agent’s table.

Source

pub fn dynamic_context_handler( self, samples: usize, handler: impl Serve + 'static, ) -> Self

Retrieve samples documents through a retrieval-family handler registered under the next context key, using the dynamic-context hook lifecycle.

Source

pub fn tool_choice(self, tool_choice: ToolChoice) -> Self

Set the tool choice.

Source

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

Set the default maximum number of turns.

Source

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

Set the sampling temperature.

Source

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

Set the output-token cap.

Source

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

Set provider passthrough parameters.

Source

pub fn options(self, options: GenerationOptions) -> Self

Set the portable generation options every request of this agent carries. A run’s AgentRunner::options overlays them field by field. Calls apply in order: this replaces every field, so a shortcut such as Self::seed called before it is lost, and one called after it sets its one field on top.

Source

pub fn reasoning(self, reasoning: impl Into<Reasoning>) -> Self

Set the reasoning level or budget in the agent’s generation options, as GenerationOptions::reasoning does, keeping its other fields. See Self::options for the order of calls.

Source

pub fn cache(self, cache: CacheRetention) -> Self

Set the cache retention in the agent’s generation options, as GenerationOptions::cache does, keeping its other fields. See Self::options for the order of calls.

Source

pub fn service_tier(self, tier: ServiceTier) -> Self

Set the service tier in the agent’s generation options, as GenerationOptions::service_tier does, keeping its other fields. See Self::options for the order of calls.

Source

pub fn verbosity(self, verbosity: Verbosity) -> Self

Set the answer verbosity in the agent’s generation options, as GenerationOptions::verbosity does, keeping its other fields. See Self::options for the order of calls.

Source

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

Set whether the model may call several tools in one turn in the agent’s generation options, as GenerationOptions::parallel_tool_calls does, keeping its other fields. See Self::options for the order of calls.

Source

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

Set the nucleus sampling probability mass in the agent’s generation options, as GenerationOptions::top_p does, keeping its other fields. See Self::options for the order of calls.

Source

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

Set the sampling seed in the agent’s generation options, as GenerationOptions::seed does, keeping its other fields. See Self::options for the order of calls.

Source

pub fn on_unsupported(self, policy: OnUnsupported) -> Self

Set what happens to an option the wire or model cannot honour in the agent’s generation options, as GenerationOptions::on_unsupported does, keeping its other fields. See Self::options for the order of calls.

Each call is checked by the model it goes to, when that model encodes it, against the catalog spec the model was connected with: a refused option fails the run under Error with nothing sent, and is dropped with a warning under Ignore. A model a run switches to checks its own calls the same way. To see every refusal before a run starts, call DynModel::check on the model.

Source

pub fn stop<S: Into<String>>(self, stop: impl IntoIterator<Item = S>) -> Self

Set the stop sequences in the agent’s generation options, as GenerationOptions::stop does, keeping its other fields. See Self::options for the order of calls.

Source

pub fn provider_options(self, options: ProviderOptions) -> Self

Set the typed per-provider options every request of this agent carries. A run’s AgentRunner::provider_options replaces the entry of each provider it names.

Calls apply in order: this replaces every entry, so an entry set by an earlier Self::provider_option is lost, and a later Self::provider_option replaces its provider’s entry on top.

Source

pub fn provider_option<O: ExtensionOptions>(self, options: O) -> Self

Store options as the entry of their provider (ExtensionOptions::Ext) in the provider options every request of this agent carries, replacing that provider’s entry and keeping every other (ProviderOptions::set). Options that do not serialize fail each request’s encode. A third-party provider reusing a built-in options type needs ProviderOptions::with::<P> and Self::provider_options: this stores under the built-in key.

Source

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

Enable or disable sensitive message content on telemetry spans. Disabled by default; enabling may expose prompts, responses, and tool data.

Source

pub fn accept_unknown_finish_reasons(self, accept: bool) -> Self

Accept finish reasons outside the normalized vocabulary (FinishReason::Other) as a normal stop. Off by default: such a turn fails the run, and history replay leaves it out. When on, the turn succeeds, its tool calls run, and it replays.

Other also holds genuine failures, such as Gemini’s MALFORMED_FUNCTION_CALL and RECITATION or Bedrock’s malformed_tool_use, so tool calls from a malformed reply may run. Filtered content still fails the turn.

Source

pub fn output_schema<T>(self) -> Self
where T: JsonSchema,

Constrain the output to T’s JSON schema.

Source

pub fn output_schema_raw(self, schema: Schema) -> Self

Constrain the output to a raw JSON schema.

Source

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

Set the structured-output mode.

Source

pub fn model_route( self, label: impl Into<ModelRef>, model: impl Into<DynModel<Completion>>, ) -> Self

Register another model the run can select by label (ModelSelectionAction::select(label), using_model(label)).

Source

pub fn model_route_handler( self, label: impl Into<ModelRef>, handler: impl Serve + 'static, ) -> Self

Register a completion-family handler under the route key for label. Includes that route in the program’s required effect row.

Source

pub fn owner(self, label: impl Into<String>) -> Self

Name the agent’s keys: <owner>/model:<label>, <owner>/retrieve:context#<n>, and its own tools’ <owner>/tool:…. Defaults to the agent’s name, or a process-local agent#<n> counter. Use stable, distinct owners for replay and agents sharing a table.

Source

pub fn memory( self, store: impl AsyncStore + WasmCompatSend + WasmCompatSync + 'static, ) -> Self

Keep each run’s conversation in store: a run loads it before its first model call and saves its messages there once it finished, so the next run goes on from them. A run that fails or is cancelled saves nothing; a failed load or save fails the run with PromptError::Memory. Of two runs that loaded the same log, even at once, the second to save fails with SessionError::Changed and adds nothing to it. Any rig-memory store will do, a host’s Arc<dyn Store> among them. See the conversation it keeps.

use rig_agent::AgentBuilder;
use rig_core::test_utils::{MockCompletionModel, MockTurn};
use rig_memory::{MemoryStore, load};

let store = MemoryStore::default();
let model = MockCompletionModel::from_turns([MockTurn::text("Hi Alice!")]);
let agent = AgentBuilder::new(model).memory(store.clone()).build();
agent.prompt("I am Alice.").conversation("alice").await?;
assert_eq!(load(&store, "alice")?.messages().len(), 2);
Source

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

The log of the memory store that runs load and save, one conversation per log: by default the agent’s name, or agent, so agents sharing a store keep apart; renaming the agent then starts a new conversation, so name the log for one that must outlive a rename. A log name is one part of a check_name name; a run on one that is not fails before its first model call.

Source

pub fn record_to(self, recorder: impl Recorder + Send + Sync) -> Self

Observe every dispatch with a caller-owned recorder, installed on the agent’s handler table at build (Handlers::record_to). Over a host’s table that is the host’s: it replaces the host’s recorder. Keep a clone of a shared recorder to inspect its observations. Agents that each own a table must not share one recorder, since each table numbers its dispatches from 1: build them over one table.

Source

pub fn add_hook<H>(self, hook: H) -> Self
where H: AgentHook + 'static,

Add a hook.

Source

pub fn build(self) -> Agent

Build the agent.

Source

pub fn new(model: impl Into<DynModel<Completion>>) -> Self

An agent over its own handler table, with model registered as the default model (label default).

Source

pub fn named_model( label: impl Into<ModelRef>, model: impl Into<DynModel<Completion>>, ) -> Self

An agent over its own handler table, with model registered under label.

Source

pub fn over_handlers( handlers: Handlers, owner: impl Into<String>, model: HandlerKey, ) -> Self

An agent over a host’s handler table, using the model under model verbatim and owner-qualified keys for the handlers it registers. The host registers the completion model before running the agent.

Source

pub fn tool_server_handle(self, handle: ToolServerHandle) -> Self

Use a pre-existing shared registry; tools added through the builder join it at build.

Source

pub fn tool<T>(self, tool: T) -> Self
where T: Tool + 'static,

Add a typed tool.

Source

pub fn dynamic_tool(self, tool: DynamicTool) -> Self

Add a runtime-defined tool.

Source

pub fn dynamic_tools(self, tools: Vec<DynamicTool>) -> Self

Add runtime-defined tools.

Source

pub fn retrieved_tools<I, F>( self, sample: usize, index: I, toolset: ToolSet, ) -> Self
where I: VectorStoreIndex<Filter = F> + 'static, F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,

Add retrievable tools chosen per request by index.

Source

pub fn retrieved_tools_handler( self, sample: usize, handler: impl Serve + 'static, toolset: ToolSet, ) -> Self

Add retrievable tools chosen per request by handler, a retrieval-family handler such as a replayer answering a recorded index; see ToolServer::retrieved_tools_handler.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WasmCompatSend for T
where T: Send,

Source§

impl<T> WasmCompatSync for T
where T: Sync,

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more