Skip to main content

rig_core/tool/
contextual.rs

1//! Contextual tool authoring and JSON-argument dispatch adapters.
2//! [`ToolContext`] carries typed inbound values and host-only result metadata;
3//! model-visible outputs retain their text, JSON, or multimodal representation.
4//!
5//! ```
6//! use rig_core::{message::ToolName, tool::{DynamicTool, ToolOutput}};
7//!
8//! let tool = DynamicTool::new_with_context(ToolName::new("echo")?, "Echo JSON", serde_json::json!({}),
9//!     |_context, args| Box::pin(async move { Ok(ToolOutput::json(args)) }));
10//! assert_eq!(tool.name(), "echo");
11//! # Ok::<(), rig_core::message::EmptyToolName>(())
12//! ```
13
14use std::{future::Future, sync::Arc};
15
16use serde::{Deserialize, Serialize};
17
18use crate::{
19    completion::{ToolAnnotations, ToolDefinition, message::ToolName},
20    serve::{ErasedHandler, adapters::ToolCallback},
21    wasm_compat::{WasmBoxedFuture, WasmCompatSend, WasmCompatSync},
22};
23
24use super::{IntoToolOutput, ToolContext, ToolExecutionError, ToolOutput, ToolResult, Touches};
25
26/// A typed LLM tool.
27///
28/// Tool authors provide metadata and exactly one execution method. Runtime
29/// context and host-only result metadata share the [`ToolContext`] path. Rig's
30/// object-safe dispatch boundary is private; use [`DynamicTool`] when the tool
31/// name or callback is only known at runtime.
32pub trait Tool: Sized + WasmCompatSend + WasmCompatSync {
33    /// Unique registration and provider-facing name.
34    const NAME: &'static str;
35    /// Typed JSON arguments.
36    type Args: for<'de> Deserialize<'de> + WasmCompatSend + WasmCompatSync;
37    /// Output convertible into Rig's canonical model presentation.
38    ///
39    /// Every owned serializable value implements [`IntoToolOutput`]
40    /// automatically. [`ToolResultContent`](crate::message::ToolResultContent)
41    /// and `Vec<ToolResultContent>` preserve rich content when returned
42    /// directly; use [`ToolOutput`] when constructing the presentation
43    /// explicitly.
44    type Output: IntoToolOutput;
45    /// Typed error returned by direct calls to this tool.
46    ///
47    /// Rig normalizes this error into [`ToolExecutionError`] only at the erased
48    /// dispatch boundary. This keeps ordinary `?` propagation and typed unit
49    /// tests available to tool authors without creating a second runtime error
50    /// representation.
51    type Error: std::error::Error + WasmCompatSend + WasmCompatSync + 'static;
52
53    /// Model-facing description: what the tool does and when to pick it
54    /// over another, such as "Use it rather than `wc` in `shell`". The
55    /// model reads it with the tool's parameters.
56    fn description(&self) -> String;
57
58    /// JSON Schema for arguments.
59    fn parameters(&self) -> serde_json::Value;
60
61    /// What calling the tool does to the world, for the host's policies
62    /// (approval, plan mode, which calls run side by side). Nothing is
63    /// stated by default, which reads as the protocol's defaults
64    /// ([`ToolAnnotations`]).
65    fn annotations(&self) -> ToolAnnotations {
66        ToolAnnotations::default()
67    }
68
69    /// What a call with `args` may read and change, so a host runs the
70    /// calls of one reply that touch different things side by side. The
71    /// default reads it from the [annotations](Self::annotations): a
72    /// read-only tool reads anything, any other writes anything.
73    fn footprint(&self, args: &Self::Args) -> Touches {
74        let _ = args;
75        Touches::from_annotations(&self.annotations())
76    }
77
78    /// Normalize a typed author-facing error for runtime policy and telemetry.
79    ///
80    /// The default preserves concrete sources for operators and exposes safe
81    /// kind-level model feedback. An existing [`ToolExecutionError`] retains its
82    /// classification and model output. Override to supply deliberate domain feedback.
83    fn map_error(&self, error: Self::Error) -> ToolExecutionError {
84        ToolExecutionError::from_error(error)
85    }
86
87    /// Execute the tool.
88    fn call(
89        &self,
90        context: &mut ToolContext,
91        args: Self::Args,
92    ) -> impl Future<Output = Result<Self::Output, Self::Error>> + WasmCompatSend;
93}
94
95/// A tool that can be retrieved from a vector store for RAG by its
96/// embedding documents.
97pub trait ToolEmbedding: Tool {
98    /// Serializable static context.
99    type Context: Serialize;
100
101    /// Documents used to retrieve the tool.
102    fn embedding_docs(&self) -> Vec<String>;
103    /// Serializable tool context.
104    fn context(&self) -> Self::Context;
105}
106
107pub(crate) fn parse_tool_args<A>(args: &str) -> Result<A, ToolExecutionError>
108where
109    A: serde::de::DeserializeOwned,
110{
111    match crate::tool::decode::decode_text(args) {
112        Ok(parsed) => Ok(parsed),
113        Err(original) if args.trim() == "null" => serde_json::from_str("{}").map_err(|_| {
114            ToolExecutionError::invalid_args(format!("failed to parse tool arguments: {original}"))
115                .with_source(original)
116        }),
117        Err(error) => Err(ToolExecutionError::invalid_args(format!(
118            "failed to parse tool arguments: {error}"
119        ))
120        .with_source(error)),
121    }
122}
123
124pub(crate) fn tool_result_from<O>(outcome: Result<O, ToolExecutionError>) -> ToolResult
125where
126    O: IntoToolOutput,
127{
128    match outcome.and_then(IntoToolOutput::into_tool_output) {
129        Ok(output) => ToolResult::success(output),
130        Err(error) => ToolResult::failed(error),
131    }
132}
133
134/// Reports whether a tool's owner still serves it. Registries check lazily on
135/// reads or reconciliation; calls before retirement may fail with a transport
136/// error rather than `HandlerUnavailable`.
137#[cfg(not(target_family = "wasm"))]
138pub type LivenessFn = Arc<dyn Fn() -> bool + Send + Sync>;
139/// A liveness probe (browser wasm: no `Send + Sync`, no threads).
140#[cfg(target_family = "wasm")]
141pub type LivenessFn = Arc<dyn Fn() -> bool>;
142
143/// A tool defined at runtime: its definition and a callback over JSON
144/// arguments. It is its own handler ([`Serve`](crate::serve::Serve)), keyed
145/// by its name. The optional liveness probe supports registry retirement;
146/// serving does not consult it.
147#[derive(Clone)]
148pub struct DynamicTool {
149    definition: ToolDefinition,
150    callback: Arc<dyn ToolCallback>,
151    liveness: Option<LivenessFn>,
152}
153
154impl DynamicTool {
155    /// Define a tool from a context-free callback over owned arguments.
156    pub fn new<F>(
157        name: ToolName,
158        description: impl Into<String>,
159        parameters: serde_json::Value,
160        callback: F,
161    ) -> Self
162    where
163        F: Fn(
164                serde_json::Value,
165            ) -> WasmBoxedFuture<'static, Result<ToolOutput, ToolExecutionError>>
166            + WasmCompatSend
167            + WasmCompatSync
168            + 'static,
169    {
170        Self::new_with_context(
171            name,
172            description,
173            parameters,
174            move |_context: &mut ToolContext, arguments| callback(arguments),
175        )
176    }
177
178    /// Define a tool from a callback over the dispatch-scoped context.
179    pub fn new_with_context<F>(
180        name: ToolName,
181        description: impl Into<String>,
182        parameters: serde_json::Value,
183        callback: F,
184    ) -> Self
185    where
186        F: ToolCallback + 'static,
187    {
188        Self {
189            definition: ToolDefinition::new(name, description, parameters),
190            callback: Arc::new(callback),
191            liveness: None,
192        }
193    }
194
195    /// The same tool, stating what calling it does to the world.
196    pub fn with_annotations(mut self, annotations: ToolAnnotations) -> Self {
197        self.definition.annotations = annotations;
198        self
199    }
200
201    /// Attach a liveness probe.
202    pub fn with_liveness<F>(mut self, is_live: F) -> Self
203    where
204        F: Fn() -> bool + WasmCompatSend + WasmCompatSync + 'static,
205    {
206        self.liveness = Some(Arc::new(is_live));
207        self
208    }
209
210    /// The tool's name.
211    pub fn name(&self) -> &ToolName {
212        &self.definition.name
213    }
214
215    /// The tool's definition.
216    pub fn definition(&self) -> ToolDefinition {
217        self.definition.clone()
218    }
219
220    /// Consumes the tool into its definition, its erased handler, and its
221    /// optional liveness probe.
222    pub fn into_parts(self) -> (ToolDefinition, ErasedHandler, Option<LivenessFn>) {
223        let Self {
224            definition,
225            callback,
226            liveness,
227        } = self;
228        let handler = ErasedHandler::new(Self {
229            definition: definition.clone(),
230            callback,
231            liveness: None,
232        });
233        (definition, handler, liveness)
234    }
235
236    /// Runs the tool on JSON `args` with an empty [`ToolContext`], as
237    /// [`Self::run_with`] does.
238    ///
239    /// ```
240    /// use rig_core::{message::ToolName, tool::{DynamicTool, ToolExecutionError, ToolOutput}};
241    /// use serde_json::json;
242    ///
243    /// let add = DynamicTool::new(ToolName::new("add")?, "Adds a and b", json!({}), |args| {
244    ///     Box::pin(async move {
245    ///         let int = |key| args.get(key).and_then(serde_json::Value::as_i64);
246    ///         let sum = int("a").zip(int("b")).map(|(a, b)| a + b);
247    ///         sum.map(|sum| ToolOutput::json(json!(sum)))
248    ///             .ok_or_else(|| ToolExecutionError::invalid_args("a and b must be integers"))
249    ///     })
250    /// });
251    /// let output = futures::executor::block_on(add.run(json!({ "a": 2, "b": 3 })))?;
252    /// assert_eq!(output.as_json(), Some(&json!(5)));
253    /// assert!(futures::executor::block_on(add.run(json!({ "a": "two" }))).is_err());
254    /// # Ok::<(), Box<dyn std::error::Error>>(())
255    /// ```
256    pub async fn run(&self, args: serde_json::Value) -> Result<ToolOutput, ToolExecutionError> {
257        self.run_with(&mut ToolContext::new(), args).await
258    }
259
260    /// Runs the tool on JSON `args` as a dispatch of its call runs it, and
261    /// returns its output or its error (invalid arguments included). The
262    /// tool sees `context`'s inbound values, and what it publishes with
263    /// `insert_result` lands in `context`. No registry or agent is involved.
264    ///
265    /// ```
266    /// use rig_core::{message::ToolName, tool::{ContextValue, DynamicTool, ToolContext, ToolOutput}};
267    /// use serde_json::json;
268    ///
269    /// #[derive(serde::Serialize, serde::Deserialize)]
270    /// struct User(String);
271    /// impl ContextValue for User { const KEY: &'static str = "user"; }
272    /// #[derive(serde::Serialize, serde::Deserialize)]
273    /// struct Greeted(bool);
274    /// impl ContextValue for Greeted { const KEY: &'static str = "greeted"; }
275    ///
276    /// let greet = DynamicTool::new_with_context(ToolName::new("greet")?, "Greets the user", json!({}),
277    ///     |context, _args| Box::pin(async move {
278    ///         let user = context.require::<User>()?;
279    ///         context.insert_result(Greeted(true))?;
280    ///         Ok(ToolOutput::text(format!("hello {}", user.0)))
281    ///     }));
282    /// let mut context = ToolContext::new();
283    /// context.insert(User("ada".into()))?;
284    /// let output = futures::executor::block_on(greet.run_with(&mut context, json!({})))?;
285    /// assert_eq!(output.as_text(), Some("hello ada"));
286    /// assert_eq!(context.result::<Greeted>()?.map(|greeted| greeted.0), Some(true));
287    /// # Ok::<(), Box<dyn std::error::Error>>(())
288    /// ```
289    pub async fn run_with(
290        &self,
291        context: &mut ToolContext,
292        args: serde_json::Value,
293    ) -> Result<ToolOutput, ToolExecutionError> {
294        crate::serve::adapters::run_direct(context, args, async |context, args| {
295            (self.callback)(context, args).await
296        })
297        .await
298    }
299
300    /// Whether the tool's owner still serves it (`true` without a probe).
301    pub fn is_live(&self) -> bool {
302        self.liveness.as_ref().is_none_or(|probe| probe())
303    }
304}
305
306impl crate::serve::Serve for DynamicTool {
307    type Family = crate::effect::family::Tool;
308
309    fn descriptor(&self) -> crate::effect::HandlerDescriptor {
310        let ToolDefinition {
311            name,
312            description,
313            parameters,
314            ..
315        } = &self.definition;
316        crate::effect::HandlerDescriptor::tool(name, description, parameters.clone())
317    }
318
319    fn key(&self) -> crate::effect::HandlerKey {
320        crate::effect::tool_key(&self.definition.name)
321    }
322
323    async fn serve(
324        &self,
325        kind: crate::effect::EffectKind,
326        dispatch: crate::serve::Dispatch,
327    ) -> crate::serve::Reply {
328        crate::serve::adapters::call_tool(kind, dispatch, None, async |context, args| {
329            (self.callback)(context, args).await
330        })
331        .await
332    }
333}
334
335impl std::fmt::Debug for DynamicTool {
336    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
337        f.debug_struct("DynamicTool")
338            .field("name", &self.definition.name)
339            .finish_non_exhaustive()
340    }
341}
342
343/// A typed tool's [`Tool::NAME`] as a [`ToolName`].
344///
345/// An empty `NAME` fails the build where this is instantiated.
346///
347/// ```
348/// use rig_core::{message::ToolChoice, tool::{Tool, ToolContext, tool_name}};
349///
350/// struct Ping;
351///
352/// impl Tool for Ping {
353///     const NAME: &'static str = "ping";
354///     type Args = serde_json::Value;
355///     type Output = String;
356///     type Error = std::convert::Infallible;
357///
358///     fn description(&self) -> String {
359///         "Replies with pong.".to_string()
360///     }
361///
362///     fn parameters(&self) -> serde_json::Value {
363///         serde_json::json!({ "type": "object" })
364///     }
365///
366///     async fn call(
367///         &self,
368///         _context: &mut ToolContext,
369///         _args: Self::Args,
370///     ) -> Result<String, Self::Error> {
371///         Ok("pong".to_string())
372///     }
373/// }
374///
375/// let choice = ToolChoice::Specific { function_names: vec![tool_name::<Ping>()] };
376/// assert_eq!(tool_name::<Ping>(), "ping");
377/// # let _ = choice;
378/// ```
379pub fn tool_name<T: Tool>() -> ToolName {
380    const { assert!(!T::NAME.is_empty(), "Tool::NAME cannot be empty") };
381    ToolName::new_unchecked(T::NAME)
382}
383
384/// A tool's [`ToolDefinition`] from a typed tool, with its annotations.
385pub fn tool_definition<T: Tool>(tool: &T) -> ToolDefinition {
386    ToolDefinition::new(tool_name::<T>(), tool.description(), tool.parameters())
387        .with_annotations(tool.annotations())
388}