Skip to main content

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;