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::runner::AgentRunner;
13use super::typed::TypedRun;
14use crate::handlers::{Handlers, ModelHandle};
15use crate::run::spec::RunSpec;
16use crate::run::{AgentRun, OutputMode};
17use crate::{
18 completion::{CompletionRequest, Message, PromptError, ToolDefinition},
19 run::response::PromptResponse,
20 tool::{
21 ToolCatalog,
22 server::{ToolServerError, ToolServerHandle},
23 },
24};
25use rig_core::completion::ModelRef;
26use rig_core::effect::{HandlerDescriptor, HandlerKey, Key, family};
27use rig_core::error::ProviderError;
28
29use rig_core::{message::ToolChoice, wasm_compat::WasmCompatSend};
30use std::sync::{
31 Arc,
32 atomic::{AtomicU64, AtomicUsize, Ordering},
33};
34
35use super::UNKNOWN_AGENT_NAME;
36
37/// What a completion request was prepared with, including the executable Rig
38/// tool names advertised to the provider for this turn.
39pub(crate) struct PreparedCompletionRequest {
40 /// The messages telemetry records for this attempt.
41 pub(crate) telemetry_messages: Vec<Arc<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<Arc<ToolDefinition>>,
49 /// The turn's tool policy, fed back to the run with the response.
50 pub(crate) policy: crate::run::TurnPolicy,
51 /// Effective structured output-token cap after runner overrides and request
52 /// patches. Does not interpret caps passed through additional parameters.
53 pub(crate) max_tokens: Option<u64>,
54}
55
56/// Retrieve tools and prepare a request from runner defaults and per-turn inputs.
57/// Pins executable registrations and the selected model for this attempt.
58/// Returns retrieval, preparation, and message-validation failures.
59pub(crate) async fn build_prepared_completion_request(
60 runner: &crate::agent::AgentRunner,
61 ctx: &crate::agent::HookContext,
62 model: &ModelHandle,
63 prompt: Arc<Message>,
64 chat_history: &[Arc<Message>],
65 committed_output_tool: Option<&str>,
66 request_patch: Option<&RequestPatch>,
67) -> Result<(CompletionRequest, PreparedCompletionRequest), ProviderError> {
68 let record_telemetry_content = runner.config.record_telemetry_content;
69 let tool_server_handle = &runner.tool_server_handle;
70
71 let retrieval_query = prompt.rag_text().or_else(|| {
72 chat_history
73 .iter()
74 .rev()
75 .find_map(|message| message.rag_text())
76 });
77
78 // Tool retrieval is a `Retrieve` dispatch at the boundary (observe-only
79 // for hooks unless one opts in), recorded like every other effect.
80 let mut dynamic_tool_ids = Vec::new();
81 for (key, kind) in tool_server_handle.retrieval_effects(retrieval_query) {
82 let ids = crate::agent::engine::dispatch_effect(runner, ctx, &key, kind)
83 .await
84 .and_then(|outcome| match outcome {
85 rig_core::effect::Answered::Documents(
86 rig_core::effect::RetrievedDocuments::Ids(ids),
87 ) => Ok(ids.into_iter().map(|(_, id)| id).collect::<Vec<String>>()),
88 other => Err(crate::agent::engine::wrong_outcome("retrieved ids", &other)),
89 })
90 .map_err(|report| {
91 ProviderError::request(format!("Failed to get tool definitions: {report}"))
92 })?;
93 dynamic_tool_ids.extend(ids);
94 }
95 let mut tool_snapshot = tool_server_handle.snapshot_with_dynamic(&dynamic_tool_ids);
96
97 let capabilities = model.capabilities();
98 let unforced = unforce_output_tool(&runner.config.spec, &capabilities);
99 let (spec, committed_output_tool) = match &unforced {
100 Some((spec, true)) => (spec, None),
101 Some((spec, false)) => (spec, committed_output_tool),
102 None => (&*runner.config.spec, committed_output_tool),
103 };
104
105 let prepared = crate::run::prepare::prepare_request(
106 spec,
107 &capabilities,
108 chat_history,
109 tool_snapshot.take_definitions(),
110 committed_output_tool,
111 request_patch,
112 )?;
113
114 // Narrow dispatch to the tools actually advertised this turn (a per-turn
115 // `active_tools` allow-list), so the implementation behind every definition
116 // the provider received is the one that runs.
117 tool_snapshot.retain_names(prepared.policy.executable());
118
119 let advertised_tools = prepared.tools.clone();
120 let policy = prepared.policy.clone();
121 let max_tokens = prepared.max_tokens;
122 // The agent records the input itself, so the request the provider sees
123 // carries the telemetry flag off: one span, no double recording.
124 let request = prepared.apply(CompletionRequest::new(prompt));
125 let telemetry_messages = if record_telemetry_content {
126 request.messages_for_telemetry()
127 } else {
128 Vec::new()
129 };
130 let prepared = PreparedCompletionRequest {
131 telemetry_messages,
132 model: model.clone(),
133 tool_snapshot: Arc::new(tool_snapshot),
134 advertised_tools,
135 policy,
136 max_tokens,
137 };
138 Ok((request, prepared))
139}
140
141/// Rig's own structured-output flow (the extractor) forces its output tool.
142/// For a model that rejects a forced tool choice, drop that force: use native
143/// structured output where the wire composes it with tools, else keep the
144/// output tool at `auto`, and say so in the preamble either way. A caller's
145/// own forced choice outside that flow is left alone. Returns the spec
146/// unforced, and whether the output tool was replaced by native output.
147fn unforce_output_tool(
148 spec: &RunSpec,
149 capabilities: &rig_core::completion::ProviderCapabilities,
150) -> Option<(RunSpec, bool)> {
151 let name = spec.output_tool_name.as_deref()?;
152 let forced = matches!(
153 spec.tool_choice,
154 Some(ToolChoice::Required | ToolChoice::Specific { .. })
155 );
156 if !capabilities.rejects_forced_tool_choice || !forced || spec.output_schema.is_none() {
157 return None;
158 }
159 let mut spec = spec.clone();
160 spec.tool_choice = None;
161 let native = capabilities.composes_native_output_with_tools;
162 let line = if native {
163 format!(
164 "The `{name}` tool is not available for this model. Reply with only the JSON \
165 object you would have passed to it."
166 )
167 } else {
168 format!("Call the `{name}` tool with your answer instead of replying in text.")
169 };
170 spec.preamble = Some(match spec.preamble.take() {
171 Some(preamble) => format!("{preamble}\n\n{line}"),
172 None => line,
173 });
174 if native {
175 spec.output_mode = OutputMode::Native;
176 }
177 Some((spec, native))
178}
179
180/// Configured model, request settings, hooks, and tool registry for runs.
181/// Per-run overrides and dynamic retrieval determine each turn's effective request.
182///
183/// Default hooks attached with [`AgentBuilder::add_hook`](crate::agent::AgentBuilder::add_hook)
184/// are used for every prompt request, plus any added on the request or runner.
185///
186/// # Example
187/// ```no_run
188/// use rig_agent::prelude::*;
189/// use rig_core::{Model, providers::openai::{self, OpenAI}};
190///
191/// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
192/// let model = OpenAI::from_env()?.completion(openai::GPT_5_2);
193///
194/// let comedian_agent = AgentBuilder::new(model)
195/// .preamble("You are a comedian here to entertain the user using humour and jokes.")
196/// .temperature(0.9)
197/// .build();
198///
199/// let response = comedian_agent.prompt("Entertain me!").await?;
200/// # Ok(())
201/// # }
202/// ```
203#[derive(Clone)]
204pub struct Agent {
205 pub(crate) config: AgentConfig,
206 pub(crate) tool_server_handle: ToolServerHandle,
207}
208
209/// Configuration shared by the builder and built agent, separate from tool state.
210#[derive(Clone)]
211pub(crate) struct AgentConfig {
212 /// Name of the agent used for logging and debugging
213 pub(crate) name: Option<String>,
214 /// Agent description. Primarily useful when using sub-agents as part of an agent workflow and converting agents to other formats.
215 pub(crate) description: Option<String>,
216 /// The handler table every run dispatches through.
217 pub(crate) handlers: Handlers,
218 /// The owner segment of every key this agent mints
219 /// (`<owner>/model:<label>`, ...).
220 pub(crate) owner: Arc<str>,
221 /// How many anonymous models this agent's values registered.
222 pub(crate) anonymous_models: Arc<AtomicUsize>,
223 /// The key of the default model in the table.
224 pub(crate) model_key: Key<family::Completion>,
225 /// The request settings and run policy: the agent's
226 /// ([`Agent::run_spec`]), and a runner's overrides on a copy of it.
227 pub(crate) spec: Arc<RunSpec>,
228 /// Whether to record sensitive request, response, and tool content on GenAI spans.
229 ///
230 /// Defaults to `false`. Enabling this can expose prompts, retrieved context,
231 /// tool results, model responses, and other sensitive or high-cardinality data
232 /// through OpenTelemetry span attributes, which can increase observability
233 /// backend storage and query costs.
234 pub(crate) record_telemetry_content: bool,
235 /// Default hook stack applied to every prompt request and runner created
236 /// from this agent. Empty by default.
237 pub(crate) hooks: HookStack,
238 /// The models registered as routes at build (`model_route`), part of
239 /// the required row: a program that can select them needs them served.
240 pub(crate) route_keys: Vec<Key<family::Completion>>,
241 /// The dynamic-context indexes registered at build
242 /// (`dynamic_context`), part of the required row: every model call
243 /// queries them.
244 pub(crate) context_keys: Vec<Key<family::Retrieve>>,
245 /// The anonymous model this value selected ([`Agent::set_model`],
246 /// [`AgentRunner::using_model_value`]); its registration lives as long
247 /// as the values sharing it.
248 pub(crate) anonymous_model: Option<Arc<AnonymousModel>>,
249 /// Where runs load their conversation from and save it to.
250 pub(crate) memory: Option<super::memory::Memory>,
251 /// The log of [`memory`](Self::memory) runs use; the agent's name, or
252 /// `agent`, when `None`.
253 pub(crate) conversation: Option<String>,
254}
255
256/// The per-process counter behind an agent's default owner label.
257static NEXT_AGENT: AtomicU64 = AtomicU64::new(0);
258
259/// The owner label an agent gets when its builder names none:
260/// `agent#<n>`, distinct per process.
261pub(crate) fn default_owner() -> String {
262 format!("agent#{}", NEXT_AGENT.fetch_add(1, Ordering::Relaxed))
263}
264
265/// The registration of a model under a generated label, scoped to the
266/// values that selected it: the last clone dropping deregisters the key.
267pub(crate) struct AnonymousModel {
268 key: Key<family::Completion>,
269 handlers: Handlers,
270}
271
272impl Drop for AnonymousModel {
273 fn drop(&mut self) {
274 self.handlers.deregister(self.key.raw());
275 }
276}
277
278/// Log a registration under a key this agent minted that the table refused:
279/// the key changed family.
280#[track_caller]
281pub(crate) fn register_generated(registered: Result<(), rig_core::error::ErrorReport>) {
282 if let Err(report) = registered {
283 let caller = std::panic::Location::caller();
284 tracing::error!(%report, %caller, "a generated key changed family; the registration was refused");
285 }
286}
287
288impl AgentConfig {
289 /// The unconfigured starting point for a builder over `model`.
290 pub(crate) fn new(handlers: Handlers, model_key: Key<family::Completion>) -> Self {
291 Self {
292 name: None,
293 description: None,
294 handlers,
295 owner: Arc::from(""),
296 anonymous_models: Arc::default(),
297 model_key,
298 spec: Arc::new(RunSpec {
299 max_turns: Some(1),
300 ..RunSpec::new()
301 }),
302 record_telemetry_content: false,
303 hooks: HookStack::new(),
304 route_keys: Vec::new(),
305 context_keys: Vec::new(),
306 anonymous_model: None,
307 memory: None,
308 conversation: None,
309 }
310 }
311
312 /// The request settings to change, copied first while shared.
313 pub(crate) fn spec_mut(&mut self) -> &mut RunSpec {
314 Arc::make_mut(&mut self.spec)
315 }
316
317 /// The model-call budget.
318 pub(crate) fn max_turns(&self) -> usize {
319 self.spec.effective_max_turns()
320 }
321
322 /// Bind the default model's typed view.
323 pub(crate) fn model_handle(&self) -> Result<ModelHandle, rig_core::error::ErrorReport> {
324 self.handlers.bind(&self.model_key)
325 }
326
327 /// The default model's label as registered now (the key's tail when
328 /// nothing serves it).
329 pub(crate) fn model_label(&self) -> ModelRef {
330 match self
331 .handlers
332 .descriptor(self.model_key.raw())
333 .map(|descriptor| descriptor.family)
334 {
335 Some(rig_core::effect::FamilyDescriptor::Completion { model, .. }) => model,
336 _ => {
337 let key = self.model_key.as_str();
338 let label = key
339 .strip_prefix(&*self.owner)
340 .and_then(|rest| rest.strip_prefix("/model:"));
341 ModelRef::new(label.unwrap_or(key))
342 }
343 }
344 }
345
346 /// Bind the model registered under `label`.
347 pub(crate) fn model_by_ref(
348 &self,
349 label: &ModelRef,
350 ) -> Result<ModelHandle, rig_core::error::ErrorReport> {
351 self.handlers.bind(&self.model_key_for(label.as_str()))
352 }
353
354 /// The key this agent mints for `suffix` (`model:<label>`,
355 /// `retrieve:context#<n>`), typed by the family registered under it.
356 pub(crate) fn key<F: rig_core::effect::Family>(&self, suffix: &str) -> Key<F> {
357 Key::new_unchecked(self.raw_key(suffix))
358 }
359
360 /// The wire key this agent mints for `suffix`.
361 pub(crate) fn raw_key(&self, suffix: &str) -> HandlerKey {
362 HandlerKey::from(format!("{}/{suffix}", self.owner))
363 }
364
365 /// The key this agent mints for the model labelled `label`.
366 pub(crate) fn model_key_for(&self, label: &str) -> Key<family::Completion> {
367 self.key(rig_core::effect::model_key(label).as_str())
368 }
369
370 /// Register `model` under `label` (replacing any model under it) and
371 /// return the key a run selects it by.
372 pub(crate) fn register_model(
373 &self,
374 label: &ModelRef,
375 model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
376 ) -> Key<family::Completion> {
377 let key = self.model_key_for(label.as_str());
378 let adapter = rig_core::serve::adapters::ModelAdapter::new(label.clone(), model.into());
379 register_generated(self.handlers.register(key.raw().clone(), adapter));
380 key
381 }
382
383 /// Register `model` under a fresh generated label and make it this
384 /// value's default; the key leaves the table when the last value
385 /// selecting it drops.
386 pub(crate) fn select_anonymous_model(
387 &mut self,
388 model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
389 ) {
390 let n = self.anonymous_models.fetch_add(1, Ordering::SeqCst);
391 let key = self.register_model(&ModelRef::new(format!("anonymous#{n}")), model);
392 self.model_key = key.clone();
393 self.anonymous_model = Some(Arc::new(AnonymousModel {
394 key,
395 handlers: self.handlers.clone(),
396 }));
397 }
398
399 /// Make the model registered under `label` this value's default.
400 pub(crate) fn select_model_label(&mut self, label: ModelRef) {
401 self.model_key = self.model_key_for(label.as_str());
402 self.anonymous_model = None;
403 }
404}
405
406impl Agent {
407 /// Return serializable request settings and run policy, excluding live models,
408 /// tools, and hooks.
409 pub fn run_spec(&self) -> RunSpec {
410 RunSpec::clone(&self.config.spec)
411 }
412}
413
414impl Agent {
415 /// The tool server this agent dispatches tool calls through. Cloning the
416 /// handle lets external tool sources (an MCP client handler, for example)
417 /// register and refresh tools the agent will see on its next turn.
418 pub fn tool_server_handle(&self) -> &crate::tool::server::ToolServerHandle {
419 &self.tool_server_handle
420 }
421
422 /// Returns the configured agent name.
423 pub fn name(&self) -> Option<&str> {
424 self.config.name.as_deref()
425 }
426
427 /// Returns the configured agent description.
428 pub fn description(&self) -> Option<&str> {
429 self.config.description.as_deref()
430 }
431
432 pub(crate) fn name_or_default(&self) -> &str {
433 self.name().unwrap_or(UNKNOWN_AGENT_NAME)
434 }
435
436 /// The key of this agent's default model in its table (a completion
437 /// key; `.raw()` for the wire string).
438 pub fn model_key(&self) -> &Key<family::Completion> {
439 &self.config.model_key
440 }
441
442 /// The descriptor of this agent's default model, as registered now.
443 pub fn model_descriptor(&self) -> Option<HandlerDescriptor> {
444 self.config.handlers.descriptor(self.config.model_key.raw())
445 }
446
447 /// The label of this agent's default model, as registered now.
448 pub fn model_label(&self) -> Option<ModelRef> {
449 self.model_descriptor()
450 .and_then(|descriptor| match descriptor.family {
451 rig_core::effect::FamilyDescriptor::Completion { model, .. } => Some(model),
452 rig_core::effect::FamilyDescriptor::Tool { .. }
453 | rig_core::effect::FamilyDescriptor::Embed { .. }
454 | rig_core::effect::FamilyDescriptor::Retrieve {}
455 | rig_core::effect::FamilyDescriptor::Rerank { .. }
456 | rig_core::effect::FamilyDescriptor::Custom { .. } => None,
457 })
458 }
459
460 /// Register `model` in this agent's table under `label` and return the
461 /// label a run selects it by.
462 pub fn register_model(
463 &self,
464 label: impl Into<ModelRef>,
465 model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
466 ) -> ModelRef {
467 let label = label.into();
468 self.config.register_model(&label, model);
469 label
470 }
471
472 /// Make the model registered under `label` this agent value's default.
473 /// Value semantics: clones of the agent keep their own default.
474 pub fn set_model_label(&mut self, label: impl Into<ModelRef>) {
475 self.config.select_model_label(label.into());
476 }
477
478 /// Register `model` under a generated label and make it this agent
479 /// value's default. The registration is scoped to the values that
480 /// select it (this agent, its clones, the runners it produces): it
481 /// leaves the table when the last of them drops or selects another model.
482 pub fn set_model(
483 &mut self,
484 model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
485 ) {
486 self.config.select_anonymous_model(model);
487 }
488
489 /// The owner segment of the keys this agent minted
490 /// (`<owner>/model:<label>`, ...): the label given to
491 /// [`AgentBuilder::owner`](crate::agent::AgentBuilder::owner), else
492 /// `agent#<n>`.
493 pub fn owner(&self) -> &str {
494 &self.config.owner
495 }
496
497 /// The handler table this agent dispatches through.
498 pub fn handlers(&self) -> &Handlers {
499 &self.config.handlers
500 }
501
502 /// [`Agent::set_model_label`] by value.
503 pub fn with_model_label(mut self, label: impl Into<ModelRef>) -> Self {
504 self.set_model_label(label);
505 self
506 }
507
508 /// [`Agent::set_model`] by value.
509 pub fn with_model(
510 mut self,
511 model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
512 ) -> Self {
513 self.set_model(model);
514 self
515 }
516
517 /// The effect row this program can dispatch to: its model, every tool
518 /// the registry serves and its retrieval indexes,
519 /// each with the family it needs, from the registry rather than what a
520 /// run happened to dispatch.
521 pub fn required_row(&self) -> rig_core::effect::EffectRow {
522 use rig_core::effect::EffectFamily;
523 let mut row = rig_core::effect::EffectRow::new();
524 row.insert(
525 self.config.model_key.raw().clone(),
526 EffectFamily::Completion,
527 );
528 for route in &self.config.route_keys {
529 row.insert(route.raw().clone(), EffectFamily::Completion);
530 }
531 for (_, tool) in self.tool_server_handle.toolset().iter() {
532 row.insert(tool.key().raw().clone(), EffectFamily::Tool);
533 }
534 for key in self.tool_server_handle.retrieval_keys() {
535 row.insert(key, EffectFamily::Retrieve);
536 }
537 for context in &self.config.context_keys {
538 row.insert(context.raw().clone(), EffectFamily::Retrieve);
539 }
540 row
541 }
542
543 /// What decides on this agent's behalf: its hook stack's names, then
544 /// every layer on its handlers (the handler table's order, outermost
545 /// in). The log's `hooks`; a replay under another stack of either is
546 /// refused.
547 pub fn program_names(&self) -> Vec<String> {
548 let mut names = self.config.hooks.names();
549 for descriptor in self.config.handlers.descriptors() {
550 names.extend(descriptor.layers);
551 }
552 names
553 }
554
555 /// The descriptor currently registered under `key`.
556 pub fn handler_descriptor(&self, key: &HandlerKey) -> Option<HandlerDescriptor> {
557 self.config.handlers.descriptor(key)
558 }
559
560 /// Resolve the provider-facing tool definitions available for a prompt.
561 ///
562 /// This read-only view does not expose tool dispatch. Agent execution and
563 /// tool lifecycle hooks remain owned by [`Self::prompt`].
564 pub async fn tool_definitions(
565 &self,
566 prompt: Option<String>,
567 ) -> Result<Vec<Arc<ToolDefinition>>, ToolServerError> {
568 self.tool_server_handle.tool_defs(prompt).await
569 }
570}
571
572impl Agent {
573 /// Start a run from `prompt`. The returned [`AgentRunner`] is the run:
574 /// configure it (history, turn budget, tool context, hooks, …), then pick
575 /// how to drive it. Nothing happens until it is driven.
576 ///
577 /// - `.await` (or [`run`](AgentRunner::run)) folds the whole loop to a
578 /// [`PromptResponse`], whose `output` is the accepted assistant text.
579 /// - [`stream`](AgentRunner::stream) yields every provider delta, tool
580 /// event and the final response as a stream.
581 /// - [`run_channel`](AgentRunner::run_channel) splits the run into a
582 /// future and an event feed for a host with its own executor or tick.
583 ///
584 /// The medium is chosen by the terminal call alone: an awaited runner asks
585 /// the provider for a complete response, a streamed one for a stream.
586 /// Hooks, tools and the resulting history are the same in each.
587 ///
588 /// ```rust,no_run
589 /// # use rig_agent::Agent;
590 /// # use futures::StreamExt;
591 /// # async fn example(agent: Agent) -> Result<(), Box<dyn std::error::Error>> {
592 /// let response = agent.prompt("What is 2 + 2?").max_turns(3).await?;
593 /// println!("{}", response.output());
594 ///
595 /// let mut stream = agent.prompt("And 3 + 3?").stream();
596 /// while let Some(item) = stream.next().await {
597 /// let item = item?;
598 /// // text deltas, tool calls and results, then `FinalResponse`
599 /// }
600 /// # Ok(())
601 /// # }
602 /// ```
603 pub fn prompt(&self, prompt: impl Into<Message>) -> AgentRunner {
604 AgentRunner::from_agent(self, prompt)
605 }
606
607 /// Continue a persisted run instead of starting one from a prompt.
608 ///
609 /// The state a driver serialized between steps (see [`AgentRun`]) is
610 /// resumed under this agent's hooks, tools, and handlers, executing pending tool
611 /// calls or requesting the next model turn.
612 /// The run is authoritative for what it persisted: its prompt, its
613 /// history, its turn budget, its invalid-tool-call retry budget and its
614 /// unhandled-invalid-tool-call policy, so
615 /// [`history`](AgentRunner::history), [`max_turns`](AgentRunner::max_turns)
616 /// and [`unhandled_invalid_tool_call`](AgentRunner::unhandled_invalid_tool_call)
617 /// on the returned runner have no effect. Everything else still comes
618 /// from the agent and the runner: the request shape (preamble, documents,
619 /// sampling parameters, additional params, tool choice, output mode),
620 /// [`add_hook`](AgentRunner::add_hook),
621 /// [`tool_context`](AgentRunner::tool_context),
622 /// [`tool_concurrency`](AgentRunner::tool_concurrency), the model
623 /// selection and telemetry settings (inbound tool context is driver
624 /// state, never part of the persisted run). Invalid-call hooks see, and a
625 /// `Skip` is gated by, the tool choice each turn was sent with. One
626 /// run-side value still shows through: the output tool the run pinned
627 /// stays pinned even though the schema and mode advertising it are the
628 /// runner's.
629 /// Unanswered tool
630 /// calls re-execute on resume: a tool that ran before the suspension but
631 /// whose result was not fed to the run runs again (at least once), while
632 /// answered calls keep their results. Drive it like any runner: `.await`,
633 /// [`stream`](AgentRunner::stream) or
634 /// [`run_channel`](AgentRunner::run_channel). The run must have been
635 /// suspended by the same rig version.
636 ///
637 /// ```rust,no_run
638 /// # use rig_agent::{Agent, AgentRun};
639 /// # async fn example(agent: Agent, saved: &str) -> Result<(), Box<dyn std::error::Error>> {
640 /// let run: AgentRun = serde_json::from_str(saved)?;
641 /// let response = agent.resume(run).tool_concurrency(4).await?;
642 /// # Ok(())
643 /// # }
644 /// ```
645 pub fn resume(&self, run: AgentRun) -> AgentRunner {
646 AgentRunner::resuming(self, run)
647 }
648
649 /// Run `prompt` against caller-owned history with the agent's defaults,
650 /// then append the messages the run committed to `chat_history`. This is
651 /// [`prompt`](Self::prompt) with [`history`](AgentRunner::history) plus
652 /// the write-back; the runner form is the one to configure or stream.
653 /// The returned [`PromptResponse`] keeps its `messages`.
654 ///
655 /// The caller's history is the run's input history and the caller owns
656 /// persistence. A run that fails appends nothing: the error carries the
657 /// history the run had, the caller's vector is unchanged.
658 #[tracing::instrument(skip(self, prompt, chat_history), fields(agent_name = self.name_or_default()))]
659 pub async fn chat(
660 &self,
661 prompt: impl Into<Message> + WasmCompatSend,
662 chat_history: &mut Vec<Message>,
663 ) -> Result<PromptResponse, PromptError> {
664 let response = AgentRunner::from_agent(self, prompt)
665 .history(chat_history.iter().cloned())
666 .await?;
667 chat_history.extend(response.messages.iter().cloned());
668 Ok(response)
669 }
670
671 /// Run `prompt` and deserialize the accepted structured response as `T`.
672 ///
673 /// The JSON schema for `T` is generated and sent to the provider as the
674 /// run's structured-output schema. Providers that support native structured
675 /// outputs constrain the model's response to match it.
676 ///
677 /// ```no_run
678 /// # async fn example(agent: rig_agent::Agent) -> Result<(), Box<dyn std::error::Error>> {
679 /// #[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
680 /// struct WeatherForecast { city: String, temperature_f: f64 }
681 /// let forecast = agent
682 /// .prompt_typed::<WeatherForecast>("What's the weather in NYC?")
683 /// .max_turns(3)
684 /// .await?
685 /// .output;
686 /// # Ok(())
687 /// # }
688 /// ```
689 pub fn prompt_typed<T>(&self, prompt: impl Into<Message>) -> TypedRun<T>
690 where
691 T: JsonSchema + DeserializeOwned + WasmCompatSend,
692 {
693 TypedRun::native(self, prompt)
694 }
695}
696
697use schemars::JsonSchema;
698use serde::de::DeserializeOwned;
699
700#[cfg(test)]
701mod request_identity_tests;