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::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}