rig_agent/agent/completion.rs
1//! Agent configuration, request preparation, and prompting entry points.
2//!
3//! ```no_run
4//! # async fn example(agent: rig_agent::Agent) -> Result<(), rig_agent::completion::PromptError> {
5//! let response = agent.prompt("Explain ownership.").await?;
6//! println!("{}", response.output());
7//! # Ok(())
8//! # }
9//! ```
10
11use super::hook::{HookStack, RequestPatch};
12use super::run::{AgentRun, OutputMode};
13use super::runner::AgentRunner;
14use super::typed::TypedRun;
15use crate::bus::{BusDriver, Dispatcher, ModelHandle};
16use crate::{
17 completion::{CompletionRequest, Document, Message, PromptError, ToolDefinition},
18 run::response::PromptResponse,
19 tool::{
20 ToolCatalog,
21 server::{ToolServerError, ToolServerHandle},
22 },
23};
24use rig_core::completion::ModelRef;
25use rig_core::effect::{HandlerDescriptor, HandlerKey, Key, family};
26use rig_core::error::ProviderError;
27use rig_core::id::ConversationId;
28
29use super::drive::AgentBus;
30use rig_core::{message::ToolChoice, wasm_compat::WasmCompatSend};
31use std::{collections::BTreeSet, sync::Arc};
32
33use super::UNKNOWN_AGENT_NAME;
34
35/// A prepared completion request plus the executable Rig tool names advertised
36/// to the provider for this turn.
37pub(crate) struct PreparedCompletionRequest {
38 /// Request prepared against the selected model's capabilities.
39 pub(crate) request: CompletionRequest,
40 /// The messages telemetry records for this attempt.
41 pub(crate) telemetry_messages: Vec<Message>,
42 /// The typed view the request is dispatched to.
43 pub(crate) model: ModelHandle,
44 /// Exact implementations behind this turn's provider definitions.
45 pub(crate) tool_snapshot: Arc<ToolCatalog>,
46 /// The definitions the request carries (executable tools plus, in Tool
47 /// output mode, the synthetic output tool), for the run's `TurnTools`.
48 pub(crate) advertised_tools: Vec<ToolDefinition>,
49 pub(crate) executable_tool_names: BTreeSet<String>,
50 pub(crate) allowed_tool_names: BTreeSet<String>,
51 /// When Tool output mode is active, the name of the synthetic output tool
52 /// advertised to the model, allowed but not executable.
53 pub(crate) output_tool_name: Option<String>,
54 /// Effective structured output-token cap after runner overrides and request
55 /// patches. Does not interpret caps passed through additional parameters.
56 pub(crate) max_tokens: Option<u64>,
57}
58
59/// Retrieve tools and prepare a request from runner defaults and per-turn inputs.
60/// Pins executable registrations and the selected model for this attempt.
61/// Returns retrieval, preparation, and message-validation failures.
62pub(crate) async fn build_prepared_completion_request(
63 runner: &crate::agent::AgentRunner,
64 ctx: &crate::agent::HookContext,
65 model: &ModelHandle,
66 prompt: Message,
67 chat_history: &[Message],
68 committed_output_tool: Option<&str>,
69 request_patch: Option<&RequestPatch>,
70) -> Result<PreparedCompletionRequest, ProviderError> {
71 let record_telemetry_content = runner.config.record_telemetry_content;
72 let tool_server_handle = &runner.tool_server_handle;
73
74 let retrieval_query = prompt.rag_text().or_else(|| {
75 chat_history
76 .iter()
77 .rev()
78 .find_map(rig_core::completion::Message::rag_text)
79 });
80
81 // Tool retrieval is a `Retrieve` dispatch at the boundary (observe-only
82 // for hooks unless one opts in), recorded like every other effect.
83 let mut dynamic_tool_ids = Vec::new();
84 for (key, kind) in tool_server_handle.retrieval_effects(retrieval_query) {
85 let ids = crate::agent::engine::dispatch_effect(
86 &runner.config.hooks,
87 ctx,
88 runner.config.bus.dispatcher(),
89 &key,
90 kind,
91 )
92 .await
93 .and_then(|outcome| match outcome {
94 rig_core::effect::Outcome::Documents(rig_core::effect::RetrievedDocuments::Ids(
95 ids,
96 )) => Ok(ids.into_iter().map(|(_, id)| id).collect::<Vec<String>>()),
97 other => Err(crate::agent::engine::wrong_outcome("retrieved ids", &other)),
98 })
99 .map_err(|report| {
100 ProviderError::request(format!("Failed to get tool definitions: {report}"))
101 })?;
102 dynamic_tool_ids.extend(ids);
103 }
104 let mut tool_snapshot = tool_server_handle.snapshot_with_dynamic(&dynamic_tool_ids);
105
106 let mut spec = runner.config.run_spec();
107 spec.output_tool_description
108 .clone_from(&runner.output_tool_description);
109 spec.augment_output_preamble = runner.augment_output_preamble;
110 let capabilities = model.capabilities();
111 let committed_output_tool = if unforce_output_tool(runner, &capabilities, &mut spec) {
112 None
113 } else {
114 committed_output_tool
115 };
116
117 let prepared = crate::run::prepare::prepare_request(
118 &spec,
119 &capabilities,
120 chat_history,
121 tool_snapshot.take_definitions(),
122 committed_output_tool,
123 request_patch,
124 )?;
125
126 // Narrow dispatch to the tools actually advertised this turn (a per-turn
127 // `active_tools` allow-list), so the implementation behind every definition
128 // the provider received is the one that runs.
129 tool_snapshot.retain_names(&prepared.executable_tool_names);
130
131 let advertised_tools = prepared.tools.clone();
132 let executable_tool_names = prepared.executable_tool_names.clone();
133 let allowed_tool_names = prepared.allowed_tool_names.clone();
134 let output_tool_name = prepared.output_tool_name.clone();
135 let max_tokens = prepared.max_tokens;
136 // The agent records the input itself, so the request the provider sees
137 // carries the telemetry flag off: one span, no double recording.
138 let request = prepared
139 .apply(CompletionRequest::new(prompt))
140 .accept_unknown_finish_reasons(runner.config.accept_unknown_finish_reasons);
141 let telemetry_messages = if record_telemetry_content {
142 request.messages_for_telemetry()
143 } else {
144 Vec::new()
145 };
146 Ok(PreparedCompletionRequest {
147 request,
148 telemetry_messages,
149 model: model.clone(),
150 tool_snapshot: Arc::new(tool_snapshot),
151 advertised_tools,
152 executable_tool_names,
153 allowed_tool_names,
154 output_tool_name,
155 max_tokens,
156 })
157}
158
159/// Rig's own structured-output flow (the extractor) forces its output tool.
160/// For a model that rejects a forced tool choice, drop that force: use native
161/// structured output where the wire composes it with tools, else keep the
162/// output tool at `auto`, and say so in the preamble either way. A caller's
163/// own forced choice outside that flow is left alone. Returns whether the
164/// output tool was replaced by native output.
165fn unforce_output_tool(
166 runner: &crate::agent::AgentRunner,
167 capabilities: &rig_core::completion::ProviderCapabilities,
168 spec: &mut crate::run::spec::RunSpec,
169) -> bool {
170 let Some(name) = runner.output_tool_name.as_deref() else {
171 return false;
172 };
173 let forced = matches!(
174 spec.tool_choice,
175 Some(ToolChoice::Required | ToolChoice::Specific { .. })
176 );
177 if !capabilities.rejects_forced_tool_choice || !forced || spec.output_schema.is_none() {
178 return false;
179 }
180 spec.tool_choice = None;
181 let native = capabilities.composes_native_output_with_tools;
182 let line = if native {
183 format!(
184 "The `{name}` tool is not available for this model. Reply with only the JSON \
185 object you would have passed to it."
186 )
187 } else {
188 format!("Call the `{name}` tool with your answer instead of replying in text.")
189 };
190 spec.preamble = Some(match spec.preamble.take() {
191 Some(preamble) => format!("{preamble}\n\n{line}"),
192 None => line,
193 });
194 if native {
195 spec.output_mode = OutputMode::Native;
196 }
197 native
198}
199
200/// Configured model, request settings, hooks, memory, and tool registry for runs.
201/// Per-run overrides and dynamic retrieval determine each turn's effective request.
202///
203/// Default hooks attached with [`AgentBuilder::add_hook`](crate::agent::AgentBuilder::add_hook)
204/// are used for every prompt request, plus any added on the request or runner.
205///
206/// # Example
207/// ```no_run
208/// use rig_agent::prelude::*;
209/// use rig_core::{Model, providers::openai::{self, OpenAI}};
210///
211/// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
212/// let model = OpenAI::from_env()?.completion(openai::GPT_5_2);
213///
214/// let comedian_agent = AgentBuilder::new(model)
215/// .preamble("You are a comedian here to entertain the user using humour and jokes.")
216/// .temperature(0.9)
217/// .build();
218///
219/// let response = comedian_agent.prompt("Entertain me!").await?;
220/// # Ok(())
221/// # }
222/// ```
223#[derive(Clone)]
224pub struct Agent {
225 pub(crate) config: AgentConfig,
226 pub(crate) tool_server_handle: ToolServerHandle,
227}
228
229/// Configuration shared by the builder and built agent, separate from tool state.
230#[derive(Clone)]
231pub(crate) struct AgentConfig {
232 /// Name of the agent used for logging and debugging
233 pub(crate) name: Option<String>,
234 /// Agent description. Primarily useful when using sub-agents as part of an agent workflow and converting agents to other formats.
235 pub(crate) description: Option<String>,
236 /// The bus every run dispatches through.
237 pub(crate) bus: AgentBus,
238 /// The key of the default model on the bus.
239 pub(crate) model_key: Key<family::Completion>,
240 /// System prompt
241 pub(crate) preamble: Option<String>,
242 /// Context documents always available to the agent
243 pub(crate) static_context: Vec<Document>,
244 /// Additional parameters to be passed to the model
245 pub(crate) additional_params: Option<serde_json::Value>,
246 /// Portable generation options every request carries.
247 pub(crate) options: rig_core::completion::GenerationOptions,
248 /// Typed per-provider options every request carries.
249 pub(crate) provider_options: rig_core::completion::ProviderOptions,
250 /// The catalog entry of the agent's model, which each model call's
251 /// options are checked against when the call goes to that model.
252 pub(crate) model_spec: Option<rig_core::catalog::ModelSpec>,
253 /// The key of the model [`Self::model_spec`] describes: the default
254 /// model the agent was built with.
255 pub(crate) model_spec_key: Option<Key<family::Completion>>,
256 /// The provider and model id of each model the builder registers from
257 /// a model value, by key suffix, until build records them on the bus.
258 pub(crate) pending_model_ids: Vec<(String, super::drive::ModelId)>,
259 /// Whether to record sensitive request, response, and tool content on GenAI spans.
260 ///
261 /// Defaults to `false`. Enabling this can expose prompts, retrieved context,
262 /// tool results, model responses, and other sensitive or high-cardinality data
263 /// through OpenTelemetry span attributes, which can increase observability
264 /// backend storage and query costs.
265 pub(crate) record_telemetry_content: bool,
266 /// Whether a finish reason outside the normalized vocabulary ends a turn
267 /// as a normal stop.
268 pub(crate) accept_unknown_finish_reasons: bool,
269 /// Maximum number of tokens for the completion
270 pub(crate) max_tokens: Option<u64>,
271 /// Temperature of the model
272 pub(crate) temperature: Option<f64>,
273 /// Whether or not the underlying LLM should be forced to use a tool before providing a response.
274 pub(crate) tool_choice: Option<ToolChoice>,
275 /// Total model-call budget, including the initial call and every retry or
276 /// continuation. Defaults to `1` (the initial call only).
277 pub(crate) max_turns: usize,
278 /// Default hook stack applied to every prompt request and runner created
279 /// from this agent. Empty by default.
280 pub(crate) hooks: HookStack,
281 /// Optional JSON Schema for structured output. When set, providers that support
282 /// native structured outputs will constrain the model's response to match this schema.
283 pub(crate) output_schema: Option<schemars::Schema>,
284 /// How the schema is conveyed: output tool, native constraint, or prompt.
285 pub(crate) output_mode: OutputMode,
286 /// Optional conversation memory backend that loads/saves history per conversation id.
287 pub(crate) memory_key: Option<Key<family::Memory>>,
288 /// The models registered as routes at build (`model_route`), part of
289 /// the required row: a program that can select them needs them served.
290 pub(crate) route_keys: Vec<Key<family::Completion>>,
291 /// The dynamic-context indexes registered at build
292 /// (`dynamic_context`), part of the required row: every model call
293 /// queries them.
294 pub(crate) context_keys: Vec<Key<family::Retrieve>>,
295 /// Optional conversation id used when none is set per-request.
296 pub(crate) conversation_id: Option<ConversationId>,
297 /// The anonymous model this value selected ([`Agent::set_model`],
298 /// [`AgentRunner::using_model_value`]); its registration lives as long
299 /// as the values sharing it.
300 pub(crate) anonymous_model: Option<std::sync::Arc<super::drive::AnonymousModel>>,
301}
302
303impl AgentConfig {
304 /// The unconfigured starting point for a builder over `model`.
305 pub(crate) fn new(bus: AgentBus, model_key: Key<family::Completion>) -> Self {
306 Self {
307 name: None,
308 description: None,
309 bus,
310 model_key,
311 preamble: None,
312 static_context: vec![],
313 additional_params: None,
314 options: rig_core::completion::GenerationOptions::default(),
315 provider_options: rig_core::completion::ProviderOptions::default(),
316 model_spec: None,
317 model_spec_key: None,
318 pending_model_ids: Vec::new(),
319 record_telemetry_content: false,
320 accept_unknown_finish_reasons: false,
321 max_tokens: None,
322 temperature: None,
323 tool_choice: None,
324 max_turns: 1,
325 hooks: HookStack::new(),
326 route_keys: Vec::new(),
327 context_keys: Vec::new(),
328 output_schema: None,
329 output_mode: OutputMode::default(),
330 memory_key: None,
331 conversation_id: None,
332 anonymous_model: None,
333 }
334 }
335
336 /// Bind the default model's typed view.
337 pub(crate) fn model_handle(&self) -> Result<ModelHandle, rig_core::error::ErrorReport> {
338 self.bus.dispatcher().bind(&self.model_key)
339 }
340
341 /// The default model's label as registered now (the key's tail when
342 /// nothing serves it).
343 pub(crate) fn model_label(&self) -> ModelRef {
344 match self
345 .bus
346 .dispatcher()
347 .descriptor(self.model_key.raw())
348 .map(|descriptor| descriptor.family)
349 {
350 Some(rig_core::effect::FamilyDescriptor::Completion { model, .. }) => model,
351 Some(rig_core::effect::FamilyDescriptor::Tool { .. })
352 | Some(rig_core::effect::FamilyDescriptor::Embed { .. })
353 | Some(rig_core::effect::FamilyDescriptor::Memory {})
354 | Some(rig_core::effect::FamilyDescriptor::Retrieve {})
355 | Some(rig_core::effect::FamilyDescriptor::Rerank { .. })
356 | Some(rig_core::effect::FamilyDescriptor::Custom { .. })
357 | None => ModelRef::new(
358 self.bus
359 .model_label(self.model_key.raw())
360 .unwrap_or(self.model_key.as_str()),
361 ),
362 }
363 }
364
365 /// Bind the model registered under `label`.
366 pub(crate) fn model_by_ref(
367 &self,
368 label: &ModelRef,
369 ) -> Result<ModelHandle, rig_core::error::ErrorReport> {
370 self.bus
371 .dispatcher()
372 .bind(&self.bus.model_key(label.as_str()))
373 }
374
375 /// Bind the memory handle, when memory is configured.
376 pub(crate) fn memory_handle(
377 &self,
378 ) -> Option<Result<crate::bus::MemoryHandle, rig_core::error::ErrorReport>> {
379 self.memory_key
380 .as_ref()
381 .map(|key| self.bus.dispatcher().bind(key))
382 }
383}
384
385impl AgentConfig {
386 /// Check `options`, which a call to the model `label` names is about to
387 /// send, against that model's catalog entry ([`AgentBuilder::model_spec`]):
388 /// a refused option fails under `OnUnsupported::Error`, and is dropped
389 /// from the call with a warning under `Ignore`. Nothing is checked
390 /// without a model spec, and a model whose entry cannot be found is let
391 /// through with a warning.
392 ///
393 /// [`AgentBuilder::model_spec`]: crate::agent::AgentBuilder::model_spec
394 pub(crate) fn check_call_options(
395 &self,
396 label: &ModelRef,
397 options: &mut rig_core::completion::GenerationOptions,
398 ) -> Result<(), rig_core::error::ProviderError> {
399 use rig_core::completion::OnUnsupported;
400 use rig_core::error::ProviderError;
401 let Some(declared) = self.model_spec.as_ref() else {
402 return Ok(());
403 };
404 let key = self.bus.model_key(label.as_str());
405 let spec = match &self.model_spec_key {
406 Some(own) if own.raw() == key.raw() => Some(declared),
407 _ => self.catalog_entry(&key, label),
408 };
409 let Some(spec) = spec else {
410 tracing::warn!(
411 model = %label,
412 "the model this call goes to has no catalog entry rig can find; its generation options are not checked"
413 );
414 return Ok(());
415 };
416 while let Err(refused) = spec.validate(options) {
417 match options.unsupported_policy() {
418 OnUnsupported::Ignore => {
419 let option: &str = refused.option.as_ref();
420 tracing::warn!(
421 option,
422 provider = %refused.provider,
423 model = %refused.model,
424 reason = %refused.reason,
425 "unsupported option ignored"
426 );
427 match option {
428 "reasoning" => options.reasoning = None,
429 "cache" => options.cache = None,
430 _ => return Err(ProviderError::UnsupportedOption(refused)),
431 }
432 }
433 _ => return Err(ProviderError::UnsupportedOption(refused)),
434 }
435 }
436 Ok(())
437 }
438
439 /// The built-in catalog's entry for the model registered under `key`:
440 /// by the provider and model id it was registered with, looked up as
441 /// the encoders look it up ([`Catalog::find`], so a dated snapshot id
442 /// finds its model), else by `label` read as a catalog reference
443 /// (`anthropic/claude-opus-4-8`).
444 ///
445 /// [`Catalog::find`]: rig_core::catalog::Catalog::find
446 fn catalog_entry(
447 &self,
448 key: &Key<family::Completion>,
449 label: &ModelRef,
450 ) -> Option<&'static rig_core::catalog::ModelSpec> {
451 use rig_core::catalog::Catalog;
452 use rig_core::providers::registry::ProviderId;
453 let catalog = Catalog::builtin();
454 match self.bus.model_id(key.raw().as_str()) {
455 Some(super::drive::ModelId {
456 provider,
457 model: Some(model),
458 }) => {
459 ProviderId::catalog(&provider).and_then(|provider| catalog.find(provider, &model))
460 }
461 Some(_) => None,
462 None => catalog.resolve(label.as_str()),
463 }
464 }
465}
466
467impl AgentConfig {
468 /// The protocol-facing half of this configuration as plain data: what a
469 /// driver needs to shape requests and budget a run, without the model,
470 /// hooks, memory or identity this config also carries.
471 pub(crate) fn run_spec(&self) -> crate::run::spec::RunSpec {
472 crate::run::spec::RunSpec {
473 preamble: self.preamble.clone(),
474 static_context: self.static_context.clone(),
475 additional_params: self.additional_params.clone(),
476 options: self.options.clone(),
477 provider_options: self.provider_options.clone(),
478 max_tokens: self.max_tokens,
479 temperature: self.temperature,
480 tool_choice: self.tool_choice.clone(),
481 max_turns: Some(self.max_turns),
482 max_invalid_tool_call_retries: 0,
483 max_consecutive_malformed_tool_calls: None,
484 output_schema: self
485 .output_schema
486 .as_ref()
487 .map(|schema| schema.as_value().clone()),
488 output_mode: self.output_mode.clone(),
489 output_tool_name: None,
490 output_tool_description: None,
491 augment_output_preamble: true,
492 unhandled_invalid_tool_call: crate::run::spec::UnhandledInvalidToolCall::Fail,
493 accept_unknown_finish_reasons: self.accept_unknown_finish_reasons,
494 }
495 }
496}
497
498impl Agent {
499 /// Return serializable request settings and run policy, excluding live models,
500 /// tools, hooks, and memory.
501 pub fn run_spec(&self) -> crate::run::spec::RunSpec {
502 self.config.run_spec()
503 }
504}
505
506impl Agent {
507 /// The tool server this agent dispatches tool calls through. Cloning the
508 /// handle lets external tool sources (an MCP client handler, for example)
509 /// register and refresh tools the agent will see on its next turn.
510 pub fn tool_server_handle(&self) -> &crate::tool::server::ToolServerHandle {
511 &self.tool_server_handle
512 }
513
514 /// Returns the configured agent name.
515 pub fn name(&self) -> Option<&str> {
516 self.config.name.as_deref()
517 }
518
519 /// Returns the configured agent description.
520 pub fn description(&self) -> Option<&str> {
521 self.config.description.as_deref()
522 }
523
524 pub(crate) fn name_or_default(&self) -> &str {
525 self.name().unwrap_or(UNKNOWN_AGENT_NAME)
526 }
527
528 /// The key of this agent's default model on its bus (a completion key;
529 /// `.raw()` for the wire string).
530 pub fn model_key(&self) -> &Key<family::Completion> {
531 &self.config.model_key
532 }
533
534 /// The descriptor of this agent's default model, as registered now.
535 pub fn model_descriptor(&self) -> Option<HandlerDescriptor> {
536 self.config
537 .bus
538 .dispatcher()
539 .descriptor(self.config.model_key.raw())
540 }
541
542 /// The label of this agent's default model, as registered now.
543 pub fn model_label(&self) -> Option<ModelRef> {
544 self.model_descriptor()
545 .and_then(|descriptor| match descriptor.family {
546 rig_core::effect::FamilyDescriptor::Completion { model, .. } => Some(model),
547 rig_core::effect::FamilyDescriptor::Tool { .. }
548 | rig_core::effect::FamilyDescriptor::Embed { .. }
549 | rig_core::effect::FamilyDescriptor::Memory {}
550 | rig_core::effect::FamilyDescriptor::Retrieve {}
551 | rig_core::effect::FamilyDescriptor::Rerank { .. }
552 | rig_core::effect::FamilyDescriptor::Custom { .. } => None,
553 })
554 }
555
556 /// Register `model` on this agent's bus under `label` and return the
557 /// label a run selects it by.
558 pub fn register_model(
559 &self,
560 label: impl Into<ModelRef>,
561 model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
562 ) -> ModelRef {
563 let label = label.into();
564 self.config.bus.register_model(&label, model);
565 label
566 }
567
568 /// Make the model registered under `label` this agent value's default.
569 /// Value semantics: clones of the agent keep their own default.
570 pub fn set_model_label(&mut self, label: impl Into<ModelRef>) {
571 self.config.model_key = self.config.bus.model_key(label.into().as_str());
572 self.config.anonymous_model = None;
573 }
574
575 /// Register `model` under a generated label and make it this agent
576 /// value's default. The registration is scoped to the values that
577 /// select it (this agent, its clones, the runners it produces): it
578 /// leaves the bus when the last of them drops or selects another model.
579 pub fn set_model(
580 &mut self,
581 model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
582 ) {
583 let anonymous = self.config.bus.register_anonymous_model(model);
584 self.config.model_key = anonymous.key().clone();
585 self.config.anonymous_model = Some(anonymous);
586 }
587
588 /// The owner segment of the keys this agent minted
589 /// (`<owner>/model:<label>`, `<owner>/memory`, ...): the label given to
590 /// [`AgentBuilder::owner`](crate::agent::AgentBuilder::owner), else
591 /// `agent#<n>`.
592 pub fn owner(&self) -> &str {
593 self.config.bus.owner()
594 }
595
596 /// [`Agent::set_model_label`] by value.
597 pub fn with_model_label(mut self, label: impl Into<ModelRef>) -> Self {
598 self.set_model_label(label);
599 self
600 }
601
602 /// [`Agent::set_model`] by value.
603 pub fn with_model(
604 mut self,
605 model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
606 ) -> Self {
607 self.set_model(model);
608 self
609 }
610
611 /// The effect row this program can dispatch to: its model, every tool
612 /// the registry serves, its memory backend and its retrieval indexes,
613 /// each with the family it needs, from the registry rather than what a
614 /// run happened to dispatch.
615 pub fn required_row(&self) -> rig_core::effect::EffectRow {
616 use rig_core::effect::EffectFamily;
617 let mut row = rig_core::effect::EffectRow::new();
618 row.insert(
619 self.config.model_key.raw().clone(),
620 EffectFamily::Completion,
621 );
622 for route in &self.config.route_keys {
623 row.insert(route.raw().clone(), EffectFamily::Completion);
624 }
625 if let Some(memory) = &self.config.memory_key {
626 row.insert(memory.raw().clone(), EffectFamily::Memory);
627 }
628 for (_, tool) in self.tool_server_handle.toolset().iter() {
629 row.insert(tool.key().raw().clone(), EffectFamily::Tool);
630 }
631 for key in self.tool_server_handle.retrieval_keys() {
632 row.insert(key, EffectFamily::Retrieve);
633 }
634 for context in &self.config.context_keys {
635 row.insert(context.raw().clone(), EffectFamily::Retrieve);
636 }
637 row
638 }
639
640 /// What decides on this agent's behalf: its hook stack's names, then
641 /// every layer on the bus's handlers (the handler table's order,
642 /// outermost in). The log's `hooks`; a replay under another stack of
643 /// either is refused.
644 pub fn program_names(&self) -> Vec<String> {
645 let mut names = self.config.hooks.names();
646 for descriptor in self.config.bus.dispatcher().descriptors() {
647 names.extend(descriptor.layers);
648 }
649 names
650 }
651
652 /// The policy this agent's own bus runs under; `None` over a host's bus.
653 pub fn bus_config(&self) -> Option<rig_core::serve::ServingPolicy> {
654 self.config.bus.config()
655 }
656
657 /// The descriptor currently registered under `key`, without access to dispatch.
658 pub fn handler_descriptor(&self, key: &HandlerKey) -> Option<HandlerDescriptor> {
659 self.config.bus.dispatcher().descriptor(key)
660 }
661
662 /// Whether this agent owns and drives its own bus driver.
663 pub fn owns_bus(&self) -> bool {
664 self.config.bus.owns_driver()
665 }
666
667 /// Take the agent apart: the dispatcher and the driver leave together,
668 /// so whoever gets the dispatcher also gets the duty to drive. Fails
669 /// when the agent was built over a host's bus or when another clone of
670 /// it still shares the driver.
671 pub fn into_parts(self) -> Result<AgentParts, Agent> {
672 let Agent {
673 mut config,
674 tool_server_handle,
675 } = self;
676 let detached = config.bus.detached();
677 let bus = std::mem::replace(&mut config.bus, detached);
678 let registrar = bus.registrar().clone();
679 match bus.try_into_parts() {
680 Ok((dispatcher, driver)) => Ok(AgentParts {
681 dispatcher,
682 registrar,
683 driver,
684 agent: Agent {
685 config,
686 tool_server_handle,
687 },
688 }),
689 Err(bus) => {
690 config.bus = bus;
691 Err(Agent {
692 config,
693 tool_server_handle,
694 })
695 }
696 }
697 }
698
699 /// Resolve the provider-facing tool definitions available for a prompt.
700 ///
701 /// This read-only view does not expose tool dispatch. Agent execution and
702 /// tool lifecycle hooks remain owned by [`Self::prompt`].
703 pub async fn tool_definitions(
704 &self,
705 prompt: Option<String>,
706 ) -> Result<Vec<ToolDefinition>, ToolServerError> {
707 self.tool_server_handle.tool_defs(prompt).await
708 }
709}
710
711impl Agent {
712 /// Start a run from `prompt`. The returned [`AgentRunner`] is the run:
713 /// configure it (history, turn budget, tool context, hooks, …), then pick
714 /// how to drive it. Nothing happens until it is driven.
715 ///
716 /// - `.await` (or [`run`](AgentRunner::run)) folds the whole loop to a
717 /// [`PromptResponse`], whose `output` is the accepted assistant text.
718 /// - [`stream`](AgentRunner::stream) yields every provider delta, tool
719 /// event and the final response as a stream.
720 /// - [`run_channel`](AgentRunner::run_channel) splits the run into a
721 /// future and an event feed for a host with its own executor or tick.
722 ///
723 /// The medium is chosen by the terminal call alone: an awaited runner asks
724 /// the provider for a complete response, a streamed one for a stream.
725 /// Hooks, tools, memory and the resulting history are the same in each.
726 ///
727 /// ```rust,no_run
728 /// # use rig_agent::Agent;
729 /// # use futures::StreamExt;
730 /// # async fn example(agent: Agent) -> Result<(), Box<dyn std::error::Error>> {
731 /// let response = agent.prompt("What is 2 + 2?").max_turns(3).await?;
732 /// println!("{}", response.output());
733 ///
734 /// let mut stream = agent.prompt("And 3 + 3?").stream();
735 /// while let Some(item) = stream.next().await {
736 /// let item = item?;
737 /// // text deltas, tool calls and results, then `FinalResponse`
738 /// }
739 /// # Ok(())
740 /// # }
741 /// ```
742 pub fn prompt(&self, prompt: impl Into<Message>) -> AgentRunner {
743 AgentRunner::from_agent(self, prompt)
744 }
745
746 /// Continue a persisted run instead of starting one from a prompt.
747 ///
748 /// The state a driver serialized between steps (see [`AgentRun`]) is
749 /// resumed under this agent's hooks, tools, and bus, executing pending tool
750 /// calls or requesting the next model turn.
751 /// The run is authoritative for what it persisted: its prompt, its
752 /// history, its turn budget, its invalid-tool-call retry budget and its
753 /// unhandled-invalid-tool-call policy, so
754 /// [`history`](AgentRunner::history), [`max_turns`](AgentRunner::max_turns)
755 /// and [`unhandled_invalid_tool_call`](AgentRunner::unhandled_invalid_tool_call)
756 /// on the returned runner have no effect. Everything else still comes
757 /// from the agent and the runner: the request shape (preamble, documents,
758 /// sampling parameters, additional params, tool choice, output mode),
759 /// [`add_hook`](AgentRunner::add_hook),
760 /// [`tool_context`](AgentRunner::tool_context),
761 /// [`tool_concurrency`](AgentRunner::tool_concurrency), the model
762 /// selection and telemetry settings (inbound tool context is driver
763 /// state, never part of the persisted run). Two run-side values still show
764 /// through: the run's persisted tool choice is what invalid-call hooks
765 /// see and what gates a `Skip`, while the request's tool choice is the
766 /// runner's; and the output tool the run committed stays committed even
767 /// though the schema and mode advertising it are the runner's.
768 /// Conversation memory is neither
769 /// loaded nor appended: the history is already in the run, and the driver
770 /// that persisted it owns memory persistence and appends the finished run's
771 /// `messages` itself, since a suspended run never reached the `Done`
772 /// append, so the response's `memory_append` is `None`. Pending tool
773 /// calls re-execute on resume: a tool that ran before the suspension and
774 /// answered nothing runs again. Drive it like any runner: `.await`,
775 /// [`stream`](AgentRunner::stream) or
776 /// [`run_channel`](AgentRunner::run_channel). The run must have been
777 /// suspended by the same rig version.
778 ///
779 /// ```rust,no_run
780 /// # use rig_agent::{Agent, AgentRun};
781 /// # async fn example(agent: Agent, saved: &str) -> Result<(), Box<dyn std::error::Error>> {
782 /// let run: AgentRun = serde_json::from_str(saved)?;
783 /// let response = agent.resume(run).tool_concurrency(4).await?;
784 /// # Ok(())
785 /// # }
786 /// ```
787 pub fn resume(&self, run: AgentRun) -> AgentRunner {
788 AgentRunner::resuming(self, run)
789 }
790
791 /// Run `prompt` against caller-owned history with the agent's defaults,
792 /// then append the messages the run committed to `chat_history`. This is
793 /// [`prompt`](Self::prompt) with [`history`](AgentRunner::history) plus
794 /// the write-back; the runner form is the one to configure or stream.
795 /// The returned [`PromptResponse`] keeps its `messages`.
796 ///
797 /// The caller's history is the run's input history, so conversation
798 /// memory is bypassed (no load, no append) and the caller owns
799 /// persistence. A run that fails appends nothing: the error carries the
800 /// history the run had, the caller's vector is unchanged.
801 #[tracing::instrument(skip(self, prompt, chat_history), fields(agent_name = self.name_or_default()))]
802 pub async fn chat(
803 &self,
804 prompt: impl Into<Message> + WasmCompatSend,
805 chat_history: &mut Vec<Message>,
806 ) -> Result<PromptResponse, PromptError> {
807 let response = AgentRunner::from_agent(self, prompt)
808 .history(chat_history.clone())
809 .await?;
810 chat_history.extend(response.messages.iter().cloned());
811 Ok(response)
812 }
813
814 /// Run `prompt` and deserialize the accepted structured response as `T`.
815 ///
816 /// The JSON schema for `T` is generated and sent to the provider as the
817 /// run's structured-output schema. Providers that support native structured
818 /// outputs constrain the model's response to match it.
819 ///
820 /// ```no_run
821 /// # async fn example(agent: rig_agent::Agent) -> Result<(), Box<dyn std::error::Error>> {
822 /// #[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
823 /// struct WeatherForecast { city: String, temperature_f: f64 }
824 /// let forecast = agent
825 /// .prompt_typed::<WeatherForecast>("What's the weather in NYC?")
826 /// .max_turns(3)
827 /// .await?
828 /// .output;
829 /// # Ok(())
830 /// # }
831 /// ```
832 pub fn prompt_typed<T>(&self, prompt: impl Into<Message>) -> TypedRun<T>
833 where
834 T: JsonSchema + DeserializeOwned + WasmCompatSend,
835 {
836 TypedRun::native(self, prompt)
837 }
838}
839
840use schemars::JsonSchema;
841use serde::de::DeserializeOwned;
842
843#[cfg(test)]
844mod request_identity_tests;
845
846/// An agent taken apart by [`Agent::into_parts`]: the same agent, now over
847/// the bus as a host would hold it, plus the dispatcher and the driver.
848pub struct AgentParts {
849 /// The bus's client half.
850 pub dispatcher: Dispatcher,
851 /// The bus's registration handle: register on the bus once the driver
852 /// is spawned.
853 pub registrar: crate::bus::Registrar,
854 /// The bus's serving half: spawn it or drive it, or the agent hangs.
855 pub driver: BusDriver,
856 /// The agent, now over the bus rather than owning it.
857 pub agent: Agent,
858}