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
139        .apply(CompletionRequest::new(prompt))
140        .accept_unknown_finish_reasons(runner.config.accept_unknown_finish_reasons);
141    let telemetry_messages = if record_telemetry_content {
142        request.messages_for_telemetry()
143    } else {
144        Vec::new()
145    };
146    Ok(PreparedCompletionRequest {
147        request,
148        telemetry_messages,
149        model: model.clone(),
150        tool_snapshot: Arc::new(tool_snapshot),
151        advertised_tools,
152        executable_tool_names,
153        allowed_tool_names,
154        output_tool_name,
155        max_tokens,
156    })
157}
158
159/// Rig's own structured-output flow (the extractor) forces its output tool.
160/// For a model that rejects a forced tool choice, drop that force: use native
161/// structured output where the wire composes it with tools, else keep the
162/// output tool at `auto`, and say so in the preamble either way. A caller's
163/// own forced choice outside that flow is left alone. Returns whether the
164/// output tool was replaced by native output.
165fn unforce_output_tool(
166    runner: &crate::agent::AgentRunner,
167    capabilities: &rig_core::completion::ProviderCapabilities,
168    spec: &mut crate::run::spec::RunSpec,
169) -> bool {
170    let Some(name) = runner.output_tool_name.as_deref() else {
171        return false;
172    };
173    let forced = matches!(
174        spec.tool_choice,
175        Some(ToolChoice::Required | ToolChoice::Specific { .. })
176    );
177    if !capabilities.rejects_forced_tool_choice || !forced || spec.output_schema.is_none() {
178        return false;
179    }
180    spec.tool_choice = None;
181    let native = capabilities.composes_native_output_with_tools;
182    let line = if native {
183        format!(
184            "The `{name}` tool is not available for this model. Reply with only the JSON \
185             object you would have passed to it."
186        )
187    } else {
188        format!("Call the `{name}` tool with your answer instead of replying in text.")
189    };
190    spec.preamble = Some(match spec.preamble.take() {
191        Some(preamble) => format!("{preamble}\n\n{line}"),
192        None => line,
193    });
194    if native {
195        spec.output_mode = OutputMode::Native;
196    }
197    native
198}
199
200/// Configured model, request settings, hooks, memory, and tool registry for runs.
201/// Per-run overrides and dynamic retrieval determine each turn's effective request.
202///
203/// Default hooks attached with [`AgentBuilder::add_hook`](crate::agent::AgentBuilder::add_hook)
204/// are used for every prompt request, plus any added on the request or runner.
205///
206/// # Example
207/// ```no_run
208/// use rig_agent::prelude::*;
209/// use rig_core::{Model, providers::openai::{self, OpenAI}};
210///
211/// # async fn run() -> Result<(), Box<dyn std::error::Error>> {
212/// let model = OpenAI::from_env()?.completion(openai::GPT_5_2);
213///
214/// let comedian_agent = AgentBuilder::new(model)
215///     .preamble("You are a comedian here to entertain the user using humour and jokes.")
216///     .temperature(0.9)
217///     .build();
218///
219/// let response = comedian_agent.prompt("Entertain me!").await?;
220/// # Ok(())
221/// # }
222/// ```
223#[derive(Clone)]
224pub struct Agent {
225    pub(crate) config: AgentConfig,
226    pub(crate) tool_server_handle: ToolServerHandle,
227}
228
229/// Configuration shared by the builder and built agent, separate from tool state.
230#[derive(Clone)]
231pub(crate) struct AgentConfig {
232    /// Name of the agent used for logging and debugging
233    pub(crate) name: Option<String>,
234    /// Agent description. Primarily useful when using sub-agents as part of an agent workflow and converting agents to other formats.
235    pub(crate) description: Option<String>,
236    /// The bus every run dispatches through.
237    pub(crate) bus: AgentBus,
238    /// The key of the default model on the bus.
239    pub(crate) model_key: Key<family::Completion>,
240    /// System prompt
241    pub(crate) preamble: Option<String>,
242    /// Context documents always available to the agent
243    pub(crate) static_context: Vec<Document>,
244    /// Additional parameters to be passed to the model
245    pub(crate) additional_params: Option<serde_json::Value>,
246    /// Portable generation options every request carries.
247    pub(crate) options: rig_core::completion::GenerationOptions,
248    /// Typed per-provider options every request carries.
249    pub(crate) provider_options: rig_core::completion::ProviderOptions,
250    /// The catalog entry of the agent's model, which each model call's
251    /// options are checked against when the call goes to that model.
252    pub(crate) model_spec: Option<rig_core::catalog::ModelSpec>,
253    /// The key of the model [`Self::model_spec`] describes: the default
254    /// model the agent was built with.
255    pub(crate) model_spec_key: Option<Key<family::Completion>>,
256    /// The provider and model id of each model the builder registers from
257    /// a model value, by key suffix, until build records them on the bus.
258    pub(crate) pending_model_ids: Vec<(String, super::drive::ModelId)>,
259    /// Whether to record sensitive request, response, and tool content on GenAI spans.
260    ///
261    /// Defaults to `false`. Enabling this can expose prompts, retrieved context,
262    /// tool results, model responses, and other sensitive or high-cardinality data
263    /// through OpenTelemetry span attributes, which can increase observability
264    /// backend storage and query costs.
265    pub(crate) record_telemetry_content: bool,
266    /// Whether a finish reason outside the normalized vocabulary ends a turn
267    /// as a normal stop.
268    pub(crate) accept_unknown_finish_reasons: bool,
269    /// Maximum number of tokens for the completion
270    pub(crate) max_tokens: Option<u64>,
271    /// Temperature of the model
272    pub(crate) temperature: Option<f64>,
273    /// Whether or not the underlying LLM should be forced to use a tool before providing a response.
274    pub(crate) tool_choice: Option<ToolChoice>,
275    /// Total model-call budget, including the initial call and every retry or
276    /// continuation. Defaults to `1` (the initial call only).
277    pub(crate) max_turns: usize,
278    /// Default hook stack applied to every prompt request and runner created
279    /// from this agent. Empty by default.
280    pub(crate) hooks: HookStack,
281    /// Optional JSON Schema for structured output. When set, providers that support
282    /// native structured outputs will constrain the model's response to match this schema.
283    pub(crate) output_schema: Option<schemars::Schema>,
284    /// How the schema is conveyed: output tool, native constraint, or prompt.
285    pub(crate) output_mode: OutputMode,
286    /// Optional conversation memory backend that loads/saves history per conversation id.
287    pub(crate) memory_key: Option<Key<family::Memory>>,
288    /// The models registered as routes at build (`model_route`), part of
289    /// the required row: a program that can select them needs them served.
290    pub(crate) route_keys: Vec<Key<family::Completion>>,
291    /// The dynamic-context indexes registered at build
292    /// (`dynamic_context`), part of the required row: every model call
293    /// queries them.
294    pub(crate) context_keys: Vec<Key<family::Retrieve>>,
295    /// Optional conversation id used when none is set per-request.
296    pub(crate) conversation_id: Option<ConversationId>,
297    /// The anonymous model this value selected ([`Agent::set_model`],
298    /// [`AgentRunner::using_model_value`]); its registration lives as long
299    /// as the values sharing it.
300    pub(crate) anonymous_model: Option<std::sync::Arc<super::drive::AnonymousModel>>,
301}
302
303impl AgentConfig {
304    /// The unconfigured starting point for a builder over `model`.
305    pub(crate) fn new(bus: AgentBus, model_key: Key<family::Completion>) -> Self {
306        Self {
307            name: None,
308            description: None,
309            bus,
310            model_key,
311            preamble: None,
312            static_context: vec![],
313            additional_params: None,
314            options: rig_core::completion::GenerationOptions::default(),
315            provider_options: rig_core::completion::ProviderOptions::default(),
316            model_spec: None,
317            model_spec_key: None,
318            pending_model_ids: Vec::new(),
319            record_telemetry_content: false,
320            accept_unknown_finish_reasons: false,
321            max_tokens: None,
322            temperature: None,
323            tool_choice: None,
324            max_turns: 1,
325            hooks: HookStack::new(),
326            route_keys: Vec::new(),
327            context_keys: Vec::new(),
328            output_schema: None,
329            output_mode: OutputMode::default(),
330            memory_key: None,
331            conversation_id: None,
332            anonymous_model: None,
333        }
334    }
335
336    /// Bind the default model's typed view.
337    pub(crate) fn model_handle(&self) -> Result<ModelHandle, rig_core::error::ErrorReport> {
338        self.bus.dispatcher().bind(&self.model_key)
339    }
340
341    /// The default model's label as registered now (the key's tail when
342    /// nothing serves it).
343    pub(crate) fn model_label(&self) -> ModelRef {
344        match self
345            .bus
346            .dispatcher()
347            .descriptor(self.model_key.raw())
348            .map(|descriptor| descriptor.family)
349        {
350            Some(rig_core::effect::FamilyDescriptor::Completion { model, .. }) => model,
351            Some(rig_core::effect::FamilyDescriptor::Tool { .. })
352            | Some(rig_core::effect::FamilyDescriptor::Embed { .. })
353            | Some(rig_core::effect::FamilyDescriptor::Memory {})
354            | Some(rig_core::effect::FamilyDescriptor::Retrieve {})
355            | Some(rig_core::effect::FamilyDescriptor::Rerank { .. })
356            | Some(rig_core::effect::FamilyDescriptor::Custom { .. })
357            | None => ModelRef::new(
358                self.bus
359                    .model_label(self.model_key.raw())
360                    .unwrap_or(self.model_key.as_str()),
361            ),
362        }
363    }
364
365    /// Bind the model registered under `label`.
366    pub(crate) fn model_by_ref(
367        &self,
368        label: &ModelRef,
369    ) -> Result<ModelHandle, rig_core::error::ErrorReport> {
370        self.bus
371            .dispatcher()
372            .bind(&self.bus.model_key(label.as_str()))
373    }
374
375    /// Bind the memory handle, when memory is configured.
376    pub(crate) fn memory_handle(
377        &self,
378    ) -> Option<Result<crate::bus::MemoryHandle, rig_core::error::ErrorReport>> {
379        self.memory_key
380            .as_ref()
381            .map(|key| self.bus.dispatcher().bind(key))
382    }
383}
384
385impl AgentConfig {
386    /// Check `options`, which a call to the model `label` names is about to
387    /// send, against that model's catalog entry ([`AgentBuilder::model_spec`]):
388    /// a refused option fails under `OnUnsupported::Error`, and is dropped
389    /// from the call with a warning under `Ignore`. Nothing is checked
390    /// without a model spec, and a model whose entry cannot be found is let
391    /// through with a warning.
392    ///
393    /// [`AgentBuilder::model_spec`]: crate::agent::AgentBuilder::model_spec
394    pub(crate) fn check_call_options(
395        &self,
396        label: &ModelRef,
397        options: &mut rig_core::completion::GenerationOptions,
398    ) -> Result<(), rig_core::error::ProviderError> {
399        use rig_core::completion::OnUnsupported;
400        use rig_core::error::ProviderError;
401        let Some(declared) = self.model_spec.as_ref() else {
402            return Ok(());
403        };
404        let key = self.bus.model_key(label.as_str());
405        let spec = match &self.model_spec_key {
406            Some(own) if own.raw() == key.raw() => Some(declared),
407            _ => self.catalog_entry(&key, label),
408        };
409        let Some(spec) = spec else {
410            tracing::warn!(
411                model = %label,
412                "the model this call goes to has no catalog entry rig can find; its generation options are not checked"
413            );
414            return Ok(());
415        };
416        while let Err(refused) = spec.validate(options) {
417            match options.unsupported_policy() {
418                OnUnsupported::Ignore => {
419                    let option: &str = refused.option.as_ref();
420                    tracing::warn!(
421                        option,
422                        provider = %refused.provider,
423                        model = %refused.model,
424                        reason = %refused.reason,
425                        "unsupported option ignored"
426                    );
427                    match option {
428                        "reasoning" => options.reasoning = None,
429                        "cache" => options.cache = None,
430                        _ => return Err(ProviderError::UnsupportedOption(refused)),
431                    }
432                }
433                _ => return Err(ProviderError::UnsupportedOption(refused)),
434            }
435        }
436        Ok(())
437    }
438
439    /// The built-in catalog's entry for the model registered under `key`:
440    /// by the provider and model id it was registered with, looked up as
441    /// the encoders look it up ([`Catalog::find`], so a dated snapshot id
442    /// finds its model), else by `label` read as a catalog reference
443    /// (`anthropic/claude-opus-4-8`).
444    ///
445    /// [`Catalog::find`]: rig_core::catalog::Catalog::find
446    fn catalog_entry(
447        &self,
448        key: &Key<family::Completion>,
449        label: &ModelRef,
450    ) -> Option<&'static rig_core::catalog::ModelSpec> {
451        use rig_core::catalog::Catalog;
452        use rig_core::providers::registry::ProviderId;
453        let catalog = Catalog::builtin();
454        match self.bus.model_id(key.raw().as_str()) {
455            Some(super::drive::ModelId {
456                provider,
457                model: Some(model),
458            }) => {
459                ProviderId::catalog(&provider).and_then(|provider| catalog.find(provider, &model))
460            }
461            Some(_) => None,
462            None => catalog.resolve(label.as_str()),
463        }
464    }
465}
466
467impl AgentConfig {
468    /// The protocol-facing half of this configuration as plain data: what a
469    /// driver needs to shape requests and budget a run, without the model,
470    /// hooks, memory or identity this config also carries.
471    pub(crate) fn run_spec(&self) -> crate::run::spec::RunSpec {
472        crate::run::spec::RunSpec {
473            preamble: self.preamble.clone(),
474            static_context: self.static_context.clone(),
475            additional_params: self.additional_params.clone(),
476            options: self.options.clone(),
477            provider_options: self.provider_options.clone(),
478            max_tokens: self.max_tokens,
479            temperature: self.temperature,
480            tool_choice: self.tool_choice.clone(),
481            max_turns: Some(self.max_turns),
482            max_invalid_tool_call_retries: 0,
483            max_consecutive_malformed_tool_calls: None,
484            output_schema: self
485                .output_schema
486                .as_ref()
487                .map(|schema| schema.as_value().clone()),
488            output_mode: self.output_mode.clone(),
489            output_tool_name: None,
490            output_tool_description: None,
491            augment_output_preamble: true,
492            unhandled_invalid_tool_call: crate::run::spec::UnhandledInvalidToolCall::Fail,
493            accept_unknown_finish_reasons: self.accept_unknown_finish_reasons,
494        }
495    }
496}
497
498impl Agent {
499    /// Return serializable request settings and run policy, excluding live models,
500    /// tools, hooks, and memory.
501    pub fn run_spec(&self) -> crate::run::spec::RunSpec {
502        self.config.run_spec()
503    }
504}
505
506impl Agent {
507    /// The tool server this agent dispatches tool calls through. Cloning the
508    /// handle lets external tool sources (an MCP client handler, for example)
509    /// register and refresh tools the agent will see on its next turn.
510    pub fn tool_server_handle(&self) -> &crate::tool::server::ToolServerHandle {
511        &self.tool_server_handle
512    }
513
514    /// Returns the configured agent name.
515    pub fn name(&self) -> Option<&str> {
516        self.config.name.as_deref()
517    }
518
519    /// Returns the configured agent description.
520    pub fn description(&self) -> Option<&str> {
521        self.config.description.as_deref()
522    }
523
524    pub(crate) fn name_or_default(&self) -> &str {
525        self.name().unwrap_or(UNKNOWN_AGENT_NAME)
526    }
527
528    /// The key of this agent's default model on its bus (a completion key;
529    /// `.raw()` for the wire string).
530    pub fn model_key(&self) -> &Key<family::Completion> {
531        &self.config.model_key
532    }
533
534    /// The descriptor of this agent's default model, as registered now.
535    pub fn model_descriptor(&self) -> Option<HandlerDescriptor> {
536        self.config
537            .bus
538            .dispatcher()
539            .descriptor(self.config.model_key.raw())
540    }
541
542    /// The label of this agent's default model, as registered now.
543    pub fn model_label(&self) -> Option<ModelRef> {
544        self.model_descriptor()
545            .and_then(|descriptor| match descriptor.family {
546                rig_core::effect::FamilyDescriptor::Completion { model, .. } => Some(model),
547                rig_core::effect::FamilyDescriptor::Tool { .. }
548                | rig_core::effect::FamilyDescriptor::Embed { .. }
549                | rig_core::effect::FamilyDescriptor::Memory {}
550                | rig_core::effect::FamilyDescriptor::Retrieve {}
551                | rig_core::effect::FamilyDescriptor::Rerank { .. }
552                | rig_core::effect::FamilyDescriptor::Custom { .. } => None,
553            })
554    }
555
556    /// Register `model` on this agent's bus under `label` and return the
557    /// label a run selects it by.
558    pub fn register_model(
559        &self,
560        label: impl Into<ModelRef>,
561        model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
562    ) -> ModelRef {
563        let label = label.into();
564        self.config.bus.register_model(&label, model);
565        label
566    }
567
568    /// Make the model registered under `label` this agent value's default.
569    /// Value semantics: clones of the agent keep their own default.
570    pub fn set_model_label(&mut self, label: impl Into<ModelRef>) {
571        self.config.model_key = self.config.bus.model_key(label.into().as_str());
572        self.config.anonymous_model = None;
573    }
574
575    /// Register `model` under a generated label and make it this agent
576    /// value's default. The registration is scoped to the values that
577    /// select it (this agent, its clones, the runners it produces): it
578    /// leaves the bus when the last of them drops or selects another model.
579    pub fn set_model(
580        &mut self,
581        model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
582    ) {
583        let anonymous = self.config.bus.register_anonymous_model(model);
584        self.config.model_key = anonymous.key().clone();
585        self.config.anonymous_model = Some(anonymous);
586    }
587
588    /// The owner segment of the keys this agent minted
589    /// (`<owner>/model:<label>`, `<owner>/memory`, ...): the label given to
590    /// [`AgentBuilder::owner`](crate::agent::AgentBuilder::owner), else
591    /// `agent#<n>`.
592    pub fn owner(&self) -> &str {
593        self.config.bus.owner()
594    }
595
596    /// [`Agent::set_model_label`] by value.
597    pub fn with_model_label(mut self, label: impl Into<ModelRef>) -> Self {
598        self.set_model_label(label);
599        self
600    }
601
602    /// [`Agent::set_model`] by value.
603    pub fn with_model(
604        mut self,
605        model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
606    ) -> Self {
607        self.set_model(model);
608        self
609    }
610
611    /// The effect row this program can dispatch to: its model, every tool
612    /// the registry serves, its memory backend and its retrieval indexes,
613    /// each with the family it needs, from the registry rather than what a
614    /// run happened to dispatch.
615    pub fn required_row(&self) -> rig_core::effect::EffectRow {
616        use rig_core::effect::EffectFamily;
617        let mut row = rig_core::effect::EffectRow::new();
618        row.insert(
619            self.config.model_key.raw().clone(),
620            EffectFamily::Completion,
621        );
622        for route in &self.config.route_keys {
623            row.insert(route.raw().clone(), EffectFamily::Completion);
624        }
625        if let Some(memory) = &self.config.memory_key {
626            row.insert(memory.raw().clone(), EffectFamily::Memory);
627        }
628        for (_, tool) in self.tool_server_handle.toolset().iter() {
629            row.insert(tool.key().raw().clone(), EffectFamily::Tool);
630        }
631        for key in self.tool_server_handle.retrieval_keys() {
632            row.insert(key, EffectFamily::Retrieve);
633        }
634        for context in &self.config.context_keys {
635            row.insert(context.raw().clone(), EffectFamily::Retrieve);
636        }
637        row
638    }
639
640    /// What decides on this agent's behalf: its hook stack's names, then
641    /// every layer on the bus's handlers (the handler table's order,
642    /// outermost in). The log's `hooks`; a replay under another stack of
643    /// either is refused.
644    pub fn program_names(&self) -> Vec<String> {
645        let mut names = self.config.hooks.names();
646        for descriptor in self.config.bus.dispatcher().descriptors() {
647            names.extend(descriptor.layers);
648        }
649        names
650    }
651
652    /// The policy this agent's own bus runs under; `None` over a host's bus.
653    pub fn bus_config(&self) -> Option<rig_core::serve::ServingPolicy> {
654        self.config.bus.config()
655    }
656
657    /// The descriptor currently registered under `key`, without access to dispatch.
658    pub fn handler_descriptor(&self, key: &HandlerKey) -> Option<HandlerDescriptor> {
659        self.config.bus.dispatcher().descriptor(key)
660    }
661
662    /// Whether this agent owns and drives its own bus driver.
663    pub fn owns_bus(&self) -> bool {
664        self.config.bus.owns_driver()
665    }
666
667    /// Take the agent apart: the dispatcher and the driver leave together,
668    /// so whoever gets the dispatcher also gets the duty to drive. Fails
669    /// when the agent was built over a host's bus or when another clone of
670    /// it still shares the driver.
671    pub fn into_parts(self) -> Result<AgentParts, Agent> {
672        let Agent {
673            mut config,
674            tool_server_handle,
675        } = self;
676        let detached = config.bus.detached();
677        let bus = std::mem::replace(&mut config.bus, detached);
678        let registrar = bus.registrar().clone();
679        match bus.try_into_parts() {
680            Ok((dispatcher, driver)) => Ok(AgentParts {
681                dispatcher,
682                registrar,
683                driver,
684                agent: Agent {
685                    config,
686                    tool_server_handle,
687                },
688            }),
689            Err(bus) => {
690                config.bus = bus;
691                Err(Agent {
692                    config,
693                    tool_server_handle,
694                })
695            }
696        }
697    }
698
699    /// Resolve the provider-facing tool definitions available for a prompt.
700    ///
701    /// This read-only view does not expose tool dispatch. Agent execution and
702    /// tool lifecycle hooks remain owned by [`Self::prompt`].
703    pub async fn tool_definitions(
704        &self,
705        prompt: Option<String>,
706    ) -> Result<Vec<ToolDefinition>, ToolServerError> {
707        self.tool_server_handle.tool_defs(prompt).await
708    }
709}
710
711impl Agent {
712    /// Start a run from `prompt`. The returned [`AgentRunner`] is the run:
713    /// configure it (history, turn budget, tool context, hooks, …), then pick
714    /// how to drive it. Nothing happens until it is driven.
715    ///
716    /// - `.await` (or [`run`](AgentRunner::run)) folds the whole loop to a
717    ///   [`PromptResponse`], whose `output` is the accepted assistant text.
718    /// - [`stream`](AgentRunner::stream) yields every provider delta, tool
719    ///   event and the final response as a stream.
720    /// - [`run_channel`](AgentRunner::run_channel) splits the run into a
721    ///   future and an event feed for a host with its own executor or tick.
722    ///
723    /// The medium is chosen by the terminal call alone: an awaited runner asks
724    /// the provider for a complete response, a streamed one for a stream.
725    /// Hooks, tools, memory and the resulting history are the same in each.
726    ///
727    /// ```rust,no_run
728    /// # use rig_agent::Agent;
729    /// # use futures::StreamExt;
730    /// # async fn example(agent: Agent) -> Result<(), Box<dyn std::error::Error>> {
731    /// let response = agent.prompt("What is 2 + 2?").max_turns(3).await?;
732    /// println!("{}", response.output());
733    ///
734    /// let mut stream = agent.prompt("And 3 + 3?").stream();
735    /// while let Some(item) = stream.next().await {
736    ///     let item = item?;
737    ///     // text deltas, tool calls and results, then `FinalResponse`
738    /// }
739    /// # Ok(())
740    /// # }
741    /// ```
742    pub fn prompt(&self, prompt: impl Into<Message>) -> AgentRunner {
743        AgentRunner::from_agent(self, prompt)
744    }
745
746    /// Continue a persisted run instead of starting one from a prompt.
747    ///
748    /// The state a driver serialized between steps (see [`AgentRun`]) is
749    /// resumed under this agent's hooks, tools, and bus, executing pending tool
750    /// calls or requesting the next model turn.
751    /// The run is authoritative for what it persisted: its prompt, its
752    /// history, its turn budget, its invalid-tool-call retry budget and its
753    /// unhandled-invalid-tool-call policy, so
754    /// [`history`](AgentRunner::history), [`max_turns`](AgentRunner::max_turns)
755    /// and [`unhandled_invalid_tool_call`](AgentRunner::unhandled_invalid_tool_call)
756    /// on the returned runner have no effect. Everything else still comes
757    /// from the agent and the runner: the request shape (preamble, documents,
758    /// sampling parameters, additional params, tool choice, output mode),
759    /// [`add_hook`](AgentRunner::add_hook),
760    /// [`tool_context`](AgentRunner::tool_context),
761    /// [`tool_concurrency`](AgentRunner::tool_concurrency), the model
762    /// selection and telemetry settings (inbound tool context is driver
763    /// state, never part of the persisted run). Two run-side values still show
764    /// through: the run's persisted tool choice is what invalid-call hooks
765    /// see and what gates a `Skip`, while the request's tool choice is the
766    /// runner's; and the output tool the run committed stays committed even
767    /// though the schema and mode advertising it are the runner's.
768    /// Conversation memory is neither
769    /// loaded nor appended: the history is already in the run, and the driver
770    /// that persisted it owns memory persistence and appends the finished run's
771    /// `messages` itself, since a suspended run never reached the `Done`
772    /// append, so the response's `memory_append` is `None`. Pending tool
773    /// calls re-execute on resume: a tool that ran before the suspension and
774    /// answered nothing runs again. Drive it like any runner: `.await`,
775    /// [`stream`](AgentRunner::stream) or
776    /// [`run_channel`](AgentRunner::run_channel). The run must have been
777    /// suspended by the same rig version.
778    ///
779    /// ```rust,no_run
780    /// # use rig_agent::{Agent, AgentRun};
781    /// # async fn example(agent: Agent, saved: &str) -> Result<(), Box<dyn std::error::Error>> {
782    /// let run: AgentRun = serde_json::from_str(saved)?;
783    /// let response = agent.resume(run).tool_concurrency(4).await?;
784    /// # Ok(())
785    /// # }
786    /// ```
787    pub fn resume(&self, run: AgentRun) -> AgentRunner {
788        AgentRunner::resuming(self, run)
789    }
790
791    /// Run `prompt` against caller-owned history with the agent's defaults,
792    /// then append the messages the run committed to `chat_history`. This is
793    /// [`prompt`](Self::prompt) with [`history`](AgentRunner::history) plus
794    /// the write-back; the runner form is the one to configure or stream.
795    /// The returned [`PromptResponse`] keeps its `messages`.
796    ///
797    /// The caller's history is the run's input history, so conversation
798    /// memory is bypassed (no load, no append) and the caller owns
799    /// persistence. A run that fails appends nothing: the error carries the
800    /// history the run had, the caller's vector is unchanged.
801    #[tracing::instrument(skip(self, prompt, chat_history), fields(agent_name = self.name_or_default()))]
802    pub async fn chat(
803        &self,
804        prompt: impl Into<Message> + WasmCompatSend,
805        chat_history: &mut Vec<Message>,
806    ) -> Result<PromptResponse, PromptError> {
807        let response = AgentRunner::from_agent(self, prompt)
808            .history(chat_history.clone())
809            .await?;
810        chat_history.extend(response.messages.iter().cloned());
811        Ok(response)
812    }
813
814    /// Run `prompt` and deserialize the accepted structured response as `T`.
815    ///
816    /// The JSON schema for `T` is generated and sent to the provider as the
817    /// run's structured-output schema. Providers that support native structured
818    /// outputs constrain the model's response to match it.
819    ///
820    /// ```no_run
821    /// # async fn example(agent: rig_agent::Agent) -> Result<(), Box<dyn std::error::Error>> {
822    /// #[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
823    /// struct WeatherForecast { city: String, temperature_f: f64 }
824    /// let forecast = agent
825    ///     .prompt_typed::<WeatherForecast>("What's the weather in NYC?")
826    ///     .max_turns(3)
827    ///     .await?
828    ///     .output;
829    /// # Ok(())
830    /// # }
831    /// ```
832    pub fn prompt_typed<T>(&self, prompt: impl Into<Message>) -> TypedRun<T>
833    where
834        T: JsonSchema + DeserializeOwned + WasmCompatSend,
835    {
836        TypedRun::native(self, prompt)
837    }
838}
839
840use schemars::JsonSchema;
841use serde::de::DeserializeOwned;
842
843#[cfg(test)]
844mod request_identity_tests;
845
846/// An agent taken apart by [`Agent::into_parts`]: the same agent, now over
847/// the bus as a host would hold it, plus the dispatcher and the driver.
848pub struct AgentParts {
849    /// The bus's client half.
850    pub dispatcher: Dispatcher,
851    /// The bus's registration handle: register on the bus once the driver
852    /// is spawned.
853    pub registrar: crate::bus::Registrar,
854    /// The bus's serving half: spawn it or drive it, or the agent hangs.
855    pub driver: BusDriver,
856    /// The agent, now over the bus rather than owning it.
857    pub agent: Agent,
858}