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}