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