1use 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
40struct DynamicContext {
44 samples: usize,
45 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
101enum DefaultModel {
104 Labelled(ModelRef, ErasedHandler),
105 Key(HandlerKey),
106}
107
108pub struct AgentBuilder {
116 config: AgentConfig,
117 tools: ToolServer,
119 shared: Option<ToolServerHandle>,
121 owner: Option<String>,
122 model: DefaultModel,
123 pending: Vec<(String, ErasedHandler)>,
125 dynamic_contexts: Vec<(String, Arc<OnceLock<Key<family::Retrieve>>>)>,
127 recorder: Option<Arc<dyn Recorder + Send + Sync>>,
128 retrieval_indexes: usize,
129 routes: Vec<String>,
131}
132
133impl AgentBuilder {
134 pub fn name(mut self, name: impl Into<String>) -> Self {
136 self.config.name = Some(name.into());
137 self
138 }
139
140 pub fn description(mut self, description: impl Into<String>) -> Self {
142 self.config.description = Some(description.into());
143 self
144 }
145
146 pub fn preamble(mut self, preamble: impl Into<String>) -> Self {
148 self.config.spec_mut().preamble = Some(preamble.into());
149 self
150 }
151
152 pub fn without_preamble(mut self) -> Self {
154 self.config.spec_mut().preamble = None;
155 self
156 }
157
158 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 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 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 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 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 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 pub fn temperature(mut self, temperature: f64) -> Self {
226 self.config.spec_mut().temperature = Some(temperature);
227 self
228 }
229
230 #[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 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 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 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 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 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 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 pub fn record_content_telemetry(mut self, enabled: bool) -> Self {
306 self.config.record_telemetry_content = enabled;
307 self
308 }
309
310 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 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 pub fn output_schema_raw(mut self, schema: Schema) -> Self {
336 self.config.spec_mut().output_schema = Some(schema);
337 self
338 }
339
340 pub fn output_mode(mut self, mode: OutputMode) -> Self {
342 self.config.spec_mut().output_mode = mode;
343 self
344 }
345
346 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 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 pub fn owner(mut self, label: impl Into<String>) -> Self {
383 self.owner = Some(label.into());
384 self
385 }
386
387 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 pub fn conversation(mut self, log: impl Into<String>) -> Self {
431 self.config.conversation = Some(log.into());
432 self
433 }
434
435 pub fn record_to(mut self, recorder: impl Recorder + Send + Sync) -> Self {
442 self.recorder = Some(Arc::new(recorder));
443 self
444 }
445
446 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 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 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 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 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 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 pub fn new(model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>) -> Self {
521 Self::named_model("default", model)
522 }
523
524 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 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 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 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 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 pub fn dynamic_tool(self, tool: DynamicTool) -> Self {
589 self.map_tools(|tools| tools.dynamic_tool(tool))
590 }
591
592 pub fn dynamic_tools(self, tools: Vec<DynamicTool>) -> Self {
594 self.map_tools(|server| server.dynamic_tools(tools))
595 }
596
597 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 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;