Skip to main content

rig_agent/agent/
builder.rs

1//! Agent construction over its own or a host's handler table, with the
2//! builder's tools, a shared tool server, or both (the builder's tools join
3//! the shared server at build).
4//!
5//! ```
6//! use rig_core::{DynModel, operation::Completion};
7//! use rig_agent::{Agent, AgentBuilder};
8//! fn assistant(model: impl Into<DynModel<Completion>>) -> Agent {
9//!     AgentBuilder::new(model).preamble("Be concise.").build()
10//! }
11//! ```
12
13use std::sync::{Arc, OnceLock};
14
15use crate::handlers::Handlers;
16use rig_core::serve::adapters::{ModelAdapter, RetrieveAdapter};
17use rig_core::serve::{ErasedHandler, Recorder};
18use rig_core::{
19    completion::{Document, ModelRef},
20    effect::{HandlerKey, Key, family},
21    vector_store::{VectorSearchRequest, VectorStoreIndex, request::DynamicSearchFilter},
22    wasm_compat::{WasmCompatSend, WasmCompatSync},
23};
24use schemars::{JsonSchema, Schema, schema_for};
25
26use crate::{
27    agent::{AgentHook, CompletionCallAction, CompletionCallEvent, HookContext, RequestPatch},
28    completion::message::ToolChoice,
29    tool::{
30        DynamicTool, Tool, ToolSet,
31        server::{ToolServer, ToolServerHandle},
32    },
33};
34
35use super::{
36    Agent, OutputMode,
37    completion::{AgentConfig, default_owner, register_generated},
38};
39
40/// The `dynamic_context` hook: retrieves documents for the prompt through
41/// the agent's handlers (an `IndexHandle` bound to the index registered at
42/// build) and patches them into the request as extra context.
43struct DynamicContext {
44    samples: usize,
45    /// The index's key, minted at build once the agent's owner is known.
46    key: Arc<OnceLock<Key<family::Retrieve>>>,
47}
48
49impl AgentHook for DynamicContext {
50    async fn on_completion_call(
51        &self,
52        ctx: &HookContext,
53        event: CompletionCallEvent<'_>,
54    ) -> CompletionCallAction {
55        let query = event.prompt.rag_text().or_else(|| {
56            event
57                .history
58                .iter()
59                .rev()
60                .find_map(|message| message.rag_text())
61        });
62        let Some(query) = query else {
63            return CompletionCallAction::continue_run();
64        };
65        let Some(key) = self.key.get() else {
66            return CompletionCallAction::stop(
67                "dynamic context is keyed at build; this hook was not built",
68            );
69        };
70        let index = match ctx.bind(key) {
71            Ok(index) => index,
72            Err(report) => {
73                return CompletionCallAction::stop(format!(
74                    "failed to bind the dynamic context index: {report}"
75                ));
76            }
77        };
78
79        let request = VectorSearchRequest::builder()
80            .query(query)
81            .samples(self.samples as u64)
82            .build();
83        match index.top_n::<serde_json::Value>(request).await {
84            Ok(results) => CompletionCallAction::patch(RequestPatch::new().extra_context(
85                results.into_iter().map(|result| {
86                    Document {
87                        text: serde_json::to_string_pretty(&result.document)
88                            .unwrap_or_else(|_| result.document.to_string()),
89                        id: result.id,
90                        additional_props: Default::default(),
91                    }
92                }),
93            )),
94            Err(error) => {
95                CompletionCallAction::stop(format!("failed to retrieve dynamic context: {error}"))
96            }
97        }
98    }
99}
100
101/// The default model: a model the builder registers under a label, or the
102/// key of one a host registers in its table.
103enum DefaultModel {
104    Labelled(ModelRef, ErasedHandler),
105    Key(HandlerKey),
106}
107
108/// Builds an [`Agent`].
109///
110/// Every handler the builder registers (the default model, model routes,
111/// dynamic-context indexes) is minted a key under the agent's owner label at
112/// build: `<owner>/model:<label>` and `<owner>/retrieve:context#<n>`. Hosts sharing a table must choose distinct
113/// owners to avoid replacing each other's bindings. The explicit owner takes
114/// precedence over the agent name, then a generated `agent#<n>` label.
115pub struct AgentBuilder {
116    config: AgentConfig,
117    /// The tools added through the builder.
118    tools: ToolServer,
119    /// The shared registry, if any; the builder's tools join it at build.
120    shared: Option<ToolServerHandle>,
121    owner: Option<String>,
122    model: DefaultModel,
123    /// Handlers to register at build, by key suffix.
124    pending: Vec<(String, ErasedHandler)>,
125    /// The dynamic-context hooks' key slots, by key suffix.
126    dynamic_contexts: Vec<(String, Arc<OnceLock<Key<family::Retrieve>>>)>,
127    recorder: Option<Arc<dyn Recorder + Send + Sync>>,
128    retrieval_indexes: usize,
129    /// The labels `model_route` registered, in order.
130    routes: Vec<String>,
131}
132
133impl AgentBuilder {
134    /// Name the agent.
135    pub fn name(mut self, name: impl Into<String>) -> Self {
136        self.config.name = Some(name.into());
137        self
138    }
139
140    /// Describe the agent.
141    pub fn description(mut self, description: impl Into<String>) -> Self {
142        self.config.description = Some(description.into());
143        self
144    }
145
146    /// Set the system prompt.
147    pub fn preamble(mut self, preamble: impl Into<String>) -> Self {
148        self.config.spec_mut().preamble = Some(preamble.into());
149        self
150    }
151
152    /// Clear the system prompt.
153    pub fn without_preamble(mut self) -> Self {
154        self.config.spec_mut().preamble = None;
155        self
156    }
157
158    /// Append a paragraph to the system prompt.
159    pub fn append_preamble(mut self, doc: &str) -> Self {
160        let preamble = &mut self.config.spec_mut().preamble;
161        *preamble = Some(format!("{}\n{doc}", preamble.take().unwrap_or_default()));
162        self
163    }
164
165    /// Add a static context document.
166    pub fn context(mut self, doc: impl Into<String>) -> Self {
167        let documents = &mut self.config.spec_mut().static_context;
168        documents.push(Document {
169            id: format!("static_doc_{}", documents.len()),
170            text: doc.into(),
171            additional_props: Default::default(),
172        });
173        self
174    }
175
176    /// Retrieve `samples` documents from `index` for every prompt and add
177    /// them as context. The index is registered in the agent's table.
178    pub fn dynamic_context<I, F>(mut self, samples: usize, index: I) -> Self
179    where
180        I: VectorStoreIndex<Filter = F> + 'static,
181        F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,
182    {
183        let n = self.retrieval_indexes;
184        self.retrieval_indexes += 1;
185        let suffix = format!("retrieve:context#{n}");
186        let key = Arc::new(OnceLock::new());
187        self.pending.push((
188            suffix.clone(),
189            ErasedHandler::new(RetrieveAdapter::new(index)),
190        ));
191        self.dynamic_contexts.push((suffix, key.clone()));
192        self.add_hook(DynamicContext { samples, key })
193    }
194
195    /// Retrieve `samples` documents through a retrieval-family handler registered
196    /// under the next context key, using the dynamic-context hook lifecycle.
197    pub fn dynamic_context_handler(
198        mut self,
199        samples: usize,
200        handler: impl rig_core::serve::Serve + 'static,
201    ) -> Self {
202        let n = self.retrieval_indexes;
203        self.retrieval_indexes += 1;
204        let suffix = format!("retrieve:context#{n}");
205        let key = Arc::new(OnceLock::new());
206        self.pending
207            .push((suffix.clone(), ErasedHandler::new(handler)));
208        self.dynamic_contexts.push((suffix, key.clone()));
209        self.add_hook(DynamicContext { samples, key })
210    }
211
212    /// Set the tool choice.
213    pub fn tool_choice(mut self, tool_choice: ToolChoice) -> Self {
214        self.config.spec_mut().tool_choice = Some(tool_choice);
215        self
216    }
217
218    /// Set the default maximum number of turns.
219    pub fn default_max_turns(mut self, default_max_turns: usize) -> Self {
220        self.config.spec_mut().max_turns = Some(default_max_turns);
221        self
222    }
223
224    /// Set the sampling temperature.
225    pub fn temperature(mut self, temperature: f64) -> Self {
226        self.config.spec_mut().temperature = Some(temperature);
227        self
228    }
229
230    /// Remove the sampling temperature, for test scenarios run against
231    /// models that reject it.
232    #[cfg(any(test, feature = "test-utils"))]
233    pub(crate) fn clear_temperature(mut self) -> Self {
234        self.config.spec_mut().temperature = None;
235        self
236    }
237
238    /// Set the output-token cap.
239    pub fn max_tokens(mut self, max_tokens: u64) -> Self {
240        self.config.spec_mut().max_tokens = Some(max_tokens);
241        self
242    }
243
244    /// Set provider passthrough parameters.
245    pub fn additional_params(mut self, params: serde_json::Value) -> Self {
246        self.config.spec_mut().additional_params = Some(params);
247        self
248    }
249
250    /// Set the portable generation options every request of this agent
251    /// carries. A run's [`AgentRunner::options`](crate::agent::AgentRunner::options)
252    /// overlays them field by field. Calls apply in order: this replaces
253    /// every field, so a shortcut such as [`Self::seed`] called before it is
254    /// lost, and one called after it sets its one field on top.
255    pub fn options(mut self, options: rig_core::completion::GenerationOptions) -> Self {
256        self.config.spec_mut().options = options;
257        self
258    }
259
260    generation_option_setters!("the agent's");
261
262    /// Set the stop sequences in the agent's generation options, as
263    /// [`GenerationOptions::stop`](rig_core::completion::GenerationOptions::stop) does,
264    /// keeping its other fields. See
265    /// [`Self::options`] for the order of calls.
266    pub fn stop<S: Into<String>>(mut self, stop: impl IntoIterator<Item = S>) -> Self {
267        self.config.spec_mut().options =
268            std::mem::take(&mut self.config.spec_mut().options).stop(stop);
269        self
270    }
271
272    /// Set the typed per-provider options every request of this agent
273    /// carries. A run's
274    /// [`AgentRunner::provider_options`](crate::agent::AgentRunner::provider_options)
275    /// replaces the entry of each provider it names.
276    ///
277    /// Calls apply in order: this replaces every entry, so an entry set by
278    /// an earlier [`Self::provider_option`] is lost, and a later
279    /// [`Self::provider_option`] replaces its provider's entry on top.
280    pub fn provider_options(mut self, options: rig_core::completion::ProviderOptions) -> Self {
281        self.config.spec_mut().provider_options = options;
282        self
283    }
284
285    /// Store `options` as the entry of their provider
286    /// ([`ExtensionOptions::Ext`](rig_core::completion::ExtensionOptions::Ext))
287    /// in the provider options every request of this agent carries,
288    /// replacing that provider's entry and keeping every other
289    /// ([`ProviderOptions::set`](rig_core::completion::ProviderOptions::set)).
290    /// Options that do not serialize fail each request's encode. A
291    /// third-party provider reusing a built-in options type needs
292    /// [`ProviderOptions::with::<P>`](rig_core::completion::ProviderOptions::with)
293    /// and [`Self::provider_options`]: this stores under the built-in key.
294    pub fn provider_option<O: rig_core::completion::ExtensionOptions>(
295        mut self,
296        options: O,
297    ) -> Self {
298        self.config.spec_mut().provider_options =
299            std::mem::take(&mut self.config.spec_mut().provider_options).set(options);
300        self
301    }
302
303    /// Enable or disable sensitive message content on telemetry spans.
304    /// Disabled by default; enabling may expose prompts, responses, and tool data.
305    pub fn record_content_telemetry(mut self, enabled: bool) -> Self {
306        self.config.record_telemetry_content = enabled;
307        self
308    }
309
310    /// Accept finish reasons outside the normalized vocabulary
311    /// ([`FinishReason::Other`](rig_core::completion::FinishReason::Other))
312    /// as a normal stop. Off by default: such a turn fails the run,
313    /// and history replay leaves it out. When on, the turn succeeds, its
314    /// tool calls run, and it replays.
315    ///
316    /// `Other` also holds genuine failures, such as Gemini's
317    /// `MALFORMED_FUNCTION_CALL` and `RECITATION` or Bedrock's
318    /// `malformed_tool_use`, so tool calls from a malformed reply may run.
319    /// Filtered content still fails the turn.
320    pub fn accept_unknown_finish_reasons(mut self, accept: bool) -> Self {
321        self.config.spec_mut().accept_unknown_finish_reasons = accept;
322        self
323    }
324
325    /// Constrain the output to `T`'s JSON schema.
326    pub fn output_schema<T>(mut self) -> Self
327    where
328        T: JsonSchema,
329    {
330        self.config.spec_mut().output_schema = Some(schema_for!(T));
331        self
332    }
333
334    /// Constrain the output to a raw JSON schema.
335    pub fn output_schema_raw(mut self, schema: Schema) -> Self {
336        self.config.spec_mut().output_schema = Some(schema);
337        self
338    }
339
340    /// Set the structured-output mode.
341    pub fn output_mode(mut self, mode: OutputMode) -> Self {
342        self.config.spec_mut().output_mode = mode;
343        self
344    }
345
346    /// Register another model the run can select by label
347    /// (`ModelSelectionAction::select(label)`, `using_model(label)`).
348    pub fn model_route(
349        mut self,
350        label: impl Into<ModelRef>,
351        model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
352    ) -> Self {
353        let label = label.into();
354        let model = model.into();
355        let suffix = rig_core::effect::model_key(label.as_str()).to_string();
356        self.routes.push(label.as_str().to_owned());
357        self.pending
358            .push((suffix, ErasedHandler::new(ModelAdapter::new(label, model))));
359        self
360    }
361
362    /// Register a completion-family handler under the route key for `label`.
363    /// Includes that route in the program's required effect row.
364    pub fn model_route_handler(
365        mut self,
366        label: impl Into<ModelRef>,
367        handler: impl rig_core::serve::Serve + 'static,
368    ) -> Self {
369        let label = label.into();
370        self.routes.push(label.as_str().to_owned());
371        self.pending.push((
372            rig_core::effect::model_key(label.as_str()).to_string(),
373            ErasedHandler::new(handler),
374        ));
375        self
376    }
377
378    /// Name the agent's keys: `<owner>/model:<label>`,
379    /// `<owner>/retrieve:context#<n>`, and its own tools' `<owner>/tool:…`.
380    /// Defaults to the agent's name, or a process-local `agent#<n>` counter.
381    /// Use stable, distinct owners for replay and agents sharing a table.
382    pub fn owner(mut self, label: impl Into<String>) -> Self {
383        self.owner = Some(label.into());
384        self
385    }
386
387    /// Keep each run's conversation in `store`: a run loads it before its
388    /// first model call and saves its messages there once it finished, so
389    /// the next run goes on from them. A run that fails or is cancelled
390    /// saves nothing; a failed load or save fails the run with
391    /// [`PromptError::Memory`](crate::completion::PromptError::Memory). Of
392    /// two runs that loaded the same log, even at once, the second to save
393    /// fails with [`SessionError::Changed`](rig_memory::SessionError::Changed)
394    /// and adds nothing to it. Any rig-memory store will do, a host's
395    /// `Arc<dyn Store>` among them. See the
396    /// [`conversation`](Self::conversation) it keeps.
397    ///
398    /// ```
399    /// use rig_agent::AgentBuilder;
400    /// use rig_core::test_utils::{MockCompletionModel, MockTurn};
401    /// use rig_memory::{MemoryStore, load};
402    ///
403    /// # tokio_test::block_on(async {
404    /// let store = MemoryStore::default();
405    /// let model = MockCompletionModel::from_turns([MockTurn::text("Hi Alice!")]);
406    /// let agent = AgentBuilder::new(model).memory(store.clone()).build();
407    /// agent.prompt("I am Alice.").conversation("alice").await?;
408    /// assert_eq!(load(&store, "alice")?.messages().len(), 2);
409    /// # Ok::<(), Box<dyn std::error::Error>>(())
410    /// # }).unwrap();
411    /// ```
412    pub fn memory(
413        mut self,
414        store: impl rig_memory::AsyncStore
415        + rig_core::wasm_compat::WasmCompatSend
416        + rig_core::wasm_compat::WasmCompatSync
417        + 'static,
418    ) -> Self {
419        self.config.memory = Some(super::memory::Memory::new(store));
420        self
421    }
422
423    /// The log of the [`memory`](Self::memory) store that runs load and
424    /// save, one conversation per log: by default the agent's
425    /// [`name`](Self::name), or `agent`, so agents sharing a store keep
426    /// apart; renaming the agent then starts a new conversation, so name
427    /// the log for one that must outlive a rename. A log name is one part
428    /// of a [`check_name`](rig_memory::check_name) name; a run on one that
429    /// is not fails before its first model call.
430    pub fn conversation(mut self, log: impl Into<String>) -> Self {
431        self.config.conversation = Some(log.into());
432        self
433    }
434
435    /// Observe every dispatch with a caller-owned recorder, installed on
436    /// the agent's handler table at build ([`Handlers::record_to`]). Over a
437    /// host's table that is the host's: it replaces the host's recorder.
438    /// Keep a clone of a shared recorder to inspect its observations.
439    /// Agents that each own a table must not share one recorder, since each
440    /// table numbers its dispatches from 1: build them over one table.
441    pub fn record_to(mut self, recorder: impl Recorder + Send + Sync) -> Self {
442        self.recorder = Some(Arc::new(recorder));
443        self
444    }
445
446    /// Add a hook.
447    pub fn add_hook<H>(mut self, hook: H) -> Self
448    where
449        H: AgentHook + 'static,
450    {
451        self.config.hooks.push(hook);
452        self
453    }
454
455    /// Build the agent.
456    pub fn build(self) -> Agent {
457        let Self {
458            mut config,
459            tools,
460            shared,
461            owner,
462            model,
463            mut pending,
464            dynamic_contexts,
465            recorder,
466            retrieval_indexes: _,
467            routes,
468        } = self;
469        // Named agents need stable keys across processes for replay.
470        config.owner = Arc::from(
471            owner
472                .or_else(|| config.name.clone())
473                .unwrap_or_else(default_owner),
474        );
475        config.model_key = match model {
476            DefaultModel::Labelled(label, handler) => {
477                let suffix = rig_core::effect::model_key(label.as_str()).to_string();
478                pending.insert(0, (suffix, handler));
479                config.model_key_for(label.as_str())
480            }
481            // A host may register its model after the agent is built; a
482            // key of another family fails the run's first model call.
483            DefaultModel::Key(key) => Key::new_unchecked(key),
484        };
485        for (suffix, handler) in pending {
486            let key = config.raw_key(&suffix);
487            register_generated(config.handlers.register_erased(key, handler));
488        }
489        for (suffix, slot) in dynamic_contexts {
490            // The slot is this builder's own, filled exactly once.
491            let key = config.key(&suffix);
492            config.context_keys.push(key.clone());
493            let _ = slot.set(key);
494        }
495        config.route_keys = routes
496            .iter()
497            .map(|label| config.model_key_for(label))
498            .collect();
499        if let Some(recorder) = recorder {
500            config.handlers.record_with(recorder);
501        }
502        let tool_server_handle = match shared {
503            Some(handle) => {
504                handle.extend(tools);
505                handle
506            }
507            // The builder's own registry takes the agent's owner, so a
508            // named agent's tool keys are stable too.
509            None => tools.owner(config.owner.to_string()).run(),
510        };
511        tool_server_handle.attach(&config.handlers);
512        Agent {
513            tool_server_handle,
514            config,
515        }
516    }
517
518    /// An agent over its own handler table, with `model` registered as the
519    /// default model (label `default`).
520    pub fn new(model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>) -> Self {
521        Self::named_model("default", model)
522    }
523
524    /// An agent over its own handler table, with `model` registered under
525    /// `label`.
526    pub fn named_model(
527        label: impl Into<ModelRef>,
528        model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
529    ) -> Self {
530        let label = label.into();
531        let handler = ErasedHandler::new(ModelAdapter::new(label.clone(), model.into()));
532        Self::start(
533            Handlers::default(),
534            None,
535            DefaultModel::Labelled(label, handler),
536        )
537    }
538
539    /// An agent over a host's handler table, using the model under `model`
540    /// verbatim and owner-qualified keys for the handlers it registers. The
541    /// host registers the completion model before running the agent.
542    pub fn over_handlers(handlers: Handlers, owner: impl Into<String>, model: HandlerKey) -> Self {
543        Self::start(handlers, Some(owner.into()), DefaultModel::Key(model))
544    }
545
546    fn start(handlers: Handlers, owner: Option<String>, model: DefaultModel) -> Self {
547        // The model key is a placeholder until build mints the real one
548        // under the owner.
549        let key = Key::new_unchecked(match &model {
550            DefaultModel::Labelled(label, _) => HandlerKey::from(label.as_str()),
551            DefaultModel::Key(key) => key.clone(),
552        });
553        Self {
554            config: AgentConfig::new(handlers, key),
555            tools: ToolServer::new(),
556            shared: None,
557            owner,
558            model,
559            pending: Vec::new(),
560            dynamic_contexts: Vec::new(),
561            recorder: None,
562            retrieval_indexes: 0,
563            routes: Vec::new(),
564        }
565    }
566
567    /// Use a pre-existing shared registry; tools added through the builder
568    /// join it at build.
569    pub fn tool_server_handle(mut self, handle: ToolServerHandle) -> Self {
570        self.shared = Some(handle);
571        self
572    }
573
574    fn map_tools(mut self, add: impl FnOnce(ToolServer) -> ToolServer) -> Self {
575        self.tools = add(std::mem::take(&mut self.tools));
576        self
577    }
578
579    /// Add a typed tool.
580    pub fn tool<T>(self, tool: T) -> Self
581    where
582        T: Tool + 'static,
583    {
584        self.map_tools(|tools| tools.tool(tool))
585    }
586
587    /// Add a runtime-defined tool.
588    pub fn dynamic_tool(self, tool: DynamicTool) -> Self {
589        self.map_tools(|tools| tools.dynamic_tool(tool))
590    }
591
592    /// Add runtime-defined tools.
593    pub fn dynamic_tools(self, tools: Vec<DynamicTool>) -> Self {
594        self.map_tools(|server| server.dynamic_tools(tools))
595    }
596
597    /// Add retrievable tools chosen per request by `index`.
598    pub fn retrieved_tools<I, F>(self, sample: usize, index: I, toolset: ToolSet) -> Self
599    where
600        I: VectorStoreIndex<Filter = F> + 'static,
601        F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,
602    {
603        self.map_tools(|tools| tools.retrieved_tools(sample, index, toolset))
604    }
605
606    /// Add retrievable tools chosen per request by `handler`, a
607    /// retrieval-family handler such as a replayer answering a recorded
608    /// index; see [`ToolServer::retrieved_tools_handler`].
609    pub fn retrieved_tools_handler(
610        self,
611        sample: usize,
612        handler: impl rig_core::serve::Serve + 'static,
613        toolset: ToolSet,
614    ) -> Self {
615        self.map_tools(|tools| tools.retrieved_tools_handler(sample, handler, toolset))
616    }
617}
618
619#[cfg(test)]
620mod tests;