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;