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