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
impl AgentBuilder
Sourcepub fn description(self, description: impl Into<String>) -> Self
pub fn description(self, description: impl Into<String>) -> Self
Describe the agent.
Sourcepub fn without_preamble(self) -> Self
pub fn without_preamble(self) -> Self
Clear the system prompt.
Sourcepub fn append_preamble(self, doc: &str) -> Self
pub fn append_preamble(self, doc: &str) -> Self
Append a paragraph to the system prompt.
Sourcepub fn dynamic_context<I, F>(self, samples: usize, index: I) -> Selfwhere
I: VectorStoreIndex<Filter = F> + 'static,
F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,
pub fn dynamic_context<I, F>(self, samples: usize, index: I) -> Selfwhere
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.
Sourcepub fn dynamic_context_handler(
self,
samples: usize,
handler: impl Serve + 'static,
) -> Self
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.
Sourcepub fn tool_choice(self, tool_choice: ToolChoice) -> Self
pub fn tool_choice(self, tool_choice: ToolChoice) -> Self
Set the tool choice.
Sourcepub fn default_max_turns(self, default_max_turns: usize) -> Self
pub fn default_max_turns(self, default_max_turns: usize) -> Self
Set the default maximum number of turns.
Sourcepub fn temperature(self, temperature: f64) -> Self
pub fn temperature(self, temperature: f64) -> Self
Set the sampling temperature.
Sourcepub fn max_tokens(self, max_tokens: u64) -> Self
pub fn max_tokens(self, max_tokens: u64) -> Self
Set the output-token cap.
Sourcepub fn additional_params(self, params: Value) -> Self
pub fn additional_params(self, params: Value) -> Self
Set provider passthrough parameters.
Sourcepub fn options(self, options: GenerationOptions) -> Self
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.
Sourcepub fn reasoning(self, reasoning: impl Into<Reasoning>) -> Self
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.
Sourcepub fn cache(self, cache: CacheRetention) -> Self
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.
Sourcepub fn service_tier(self, tier: ServiceTier) -> Self
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.
Sourcepub fn verbosity(self, verbosity: Verbosity) -> Self
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.
Sourcepub fn parallel_tool_calls(self, parallel: bool) -> Self
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.
Sourcepub fn top_p(self, top_p: f64) -> Self
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.
Sourcepub fn seed(self, seed: u64) -> Self
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.
Sourcepub fn on_unsupported(self, policy: OnUnsupported) -> Self
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.
Sourcepub fn stop<S: Into<String>>(self, stop: impl IntoIterator<Item = S>) -> Self
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.
Sourcepub fn provider_options(self, options: ProviderOptions) -> Self
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.
Sourcepub fn provider_option<O: ExtensionOptions>(self, options: O) -> Self
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.
Sourcepub fn record_content_telemetry(self, enabled: bool) -> Self
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.
Sourcepub fn accept_unknown_finish_reasons(self, accept: bool) -> Self
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.
Sourcepub fn output_schema<T>(self) -> Selfwhere
T: JsonSchema,
pub fn output_schema<T>(self) -> Selfwhere
T: JsonSchema,
Constrain the output to T’s JSON schema.
Sourcepub fn output_schema_raw(self, schema: Schema) -> Self
pub fn output_schema_raw(self, schema: Schema) -> Self
Constrain the output to a raw JSON schema.
Sourcepub fn output_mode(self, mode: OutputMode) -> Self
pub fn output_mode(self, mode: OutputMode) -> Self
Set the structured-output mode.
Sourcepub fn model_route(
self,
label: impl Into<ModelRef>,
model: impl Into<DynModel<Completion>>,
) -> Self
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)).
Sourcepub fn model_route_handler(
self,
label: impl Into<ModelRef>,
handler: impl Serve + 'static,
) -> Self
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.
Sourcepub fn owner(self, label: impl Into<String>) -> Self
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.
Sourcepub fn memory(
self,
store: impl AsyncStore + WasmCompatSend + WasmCompatSync + 'static,
) -> Self
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);Sourcepub fn conversation(self, log: impl Into<String>) -> Self
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.
Sourcepub fn record_to(self, recorder: impl Recorder + Send + Sync) -> Self
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.
Sourcepub fn new(model: impl Into<DynModel<Completion>>) -> Self
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).
Sourcepub fn named_model(
label: impl Into<ModelRef>,
model: impl Into<DynModel<Completion>>,
) -> Self
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.
Sourcepub fn over_handlers(
handlers: Handlers,
owner: impl Into<String>,
model: HandlerKey,
) -> Self
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.
Sourcepub fn tool_server_handle(self, handle: ToolServerHandle) -> Self
pub fn tool_server_handle(self, handle: ToolServerHandle) -> Self
Use a pre-existing shared registry; tools added through the builder join it at build.
Sourcepub fn dynamic_tool(self, tool: DynamicTool) -> Self
pub fn dynamic_tool(self, tool: DynamicTool) -> Self
Add a runtime-defined tool.
Sourcepub fn dynamic_tools(self, tools: Vec<DynamicTool>) -> Self
pub fn dynamic_tools(self, tools: Vec<DynamicTool>) -> Self
Add runtime-defined tools.
Sourcepub fn retrieved_tools<I, F>(
self,
sample: usize,
index: I,
toolset: ToolSet,
) -> Selfwhere
I: VectorStoreIndex<Filter = F> + 'static,
F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,
pub fn retrieved_tools<I, F>(
self,
sample: usize,
index: I,
toolset: ToolSet,
) -> Selfwhere
I: VectorStoreIndex<Filter = F> + 'static,
F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,
Add retrievable tools chosen per request by index.
Sourcepub fn retrieved_tools_handler(
self,
sample: usize,
handler: impl Serve + 'static,
toolset: ToolSet,
) -> Self
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.