Struct DynamicTool 

pub struct DynamicTool { /* private fields */ }

A tool defined at runtime: its definition and a callback over JSON arguments. It is its own handler (Serve), keyed by its name. The optional liveness probe supports registry retirement; serving does not consult it.

Implementations

impl DynamicTool

pub fn new<F>( name: ToolName, description: impl Into<String>, parameters: Value, callback: F, ) -> Self

where F: Fn(Value) -> WasmBoxedFuture<'static, Result<ToolOutput, ToolExecutionError>> + WasmCompatSend + WasmCompatSync + 'static,

Define a tool from a context-free callback over owned arguments.

pub fn new_with_context<F>( name: ToolName, description: impl Into<String>, parameters: Value, callback: F, ) -> Self

where F: ToolCallback + 'static,

Define a tool from a callback over the dispatch-scoped context.

pub fn with_annotations(self, annotations: ToolAnnotations) -> Self

The same tool, stating what calling it does to the world.

pub fn with_liveness<F>(self, is_live: F) -> Self

where F: Fn() -> bool + WasmCompatSend + WasmCompatSync + 'static,

Attach a liveness probe.

pub fn name(&self) -> &ToolName

The tool’s name.

pub fn definition(&self) -> ToolDefinition

The tool’s definition.

pub fn into_parts(self) -> (ToolDefinition, ErasedHandler, Option<LivenessFn>)

Consumes the tool into its definition, its erased handler, and its optional liveness probe.

pub async fn run(&self, args: Value) -> Result<ToolOutput, ToolExecutionError>

Runs the tool on JSON args with an empty ToolContext, as Self::run_with does.

use rig_core::{message::ToolName, tool::{DynamicTool, ToolExecutionError, ToolOutput}};
use serde_json::json;

let add = DynamicTool::new(ToolName::new("add")?, "Adds a and b", json!({}), |args| {
    Box::pin(async move {
        let int = |key| args.get(key).and_then(serde_json::Value::as_i64);
        let sum = int("a").zip(int("b")).map(|(a, b)| a + b);
        sum.map(|sum| ToolOutput::json(json!(sum)))
            .ok_or_else(|| ToolExecutionError::invalid_args("a and b must be integers"))
    })
});
let output = futures::executor::block_on(add.run(json!({ "a": 2, "b": 3 })))?;
assert_eq!(output.as_json(), Some(&json!(5)));
assert!(futures::executor::block_on(add.run(json!({ "a": "two" }))).is_err());

pub async fn run_with( &self, context: &mut ToolContext, args: Value, ) -> Result<ToolOutput, ToolExecutionError>

Runs the tool on JSON args as a dispatch of its call runs it, and returns its output or its error (invalid arguments included). The tool sees context’s inbound values, and what it publishes with insert_result lands in context. No registry or agent is involved.

use rig_core::{message::ToolName, tool::{ContextValue, DynamicTool, ToolContext, ToolOutput}};
use serde_json::json;

#[derive(serde::Serialize, serde::Deserialize)]
struct User(String);
impl ContextValue for User { const KEY: &'static str = "user"; }
#[derive(serde::Serialize, serde::Deserialize)]
struct Greeted(bool);
impl ContextValue for Greeted { const KEY: &'static str = "greeted"; }

let greet = DynamicTool::new_with_context(ToolName::new("greet")?, "Greets the user", json!({}),
    |context, _args| Box::pin(async move {
        let user = context.require::<User>()?;
        context.insert_result(Greeted(true))?;
        Ok(ToolOutput::text(format!("hello {}", user.0)))
    }));
let mut context = ToolContext::new();
context.insert(User("ada".into()))?;
let output = futures::executor::block_on(greet.run_with(&mut context, json!({})))?;
assert_eq!(output.as_text(), Some("hello ada"));
assert_eq!(context.result::<Greeted>()?.map(|greeted| greeted.0), Some(true));

pub fn is_live(&self) -> bool

Whether the tool’s owner still serves it (true without a probe).

Trait Implementations

impl Clone for DynamicTool

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DynamicTool

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Serve for DynamicTool

type Family = Tool

The family this handler serves, or Dynamic.

fn descriptor(&self) -> HandlerDescriptor

What this handler is: the family-keyed description a typed view checks at bind time and a scene serializes.

fn key(&self) -> HandlerKey

The descriptor’s key. A handler whose descriptor is costly to build, such as a tool’s argument schema, says it without building one.

async fn serve(&self, kind: EffectKind, dispatch: Dispatch) -> Reply

Prepare an outcome or an owned stream for the driver to consume.

fn footprint(&self, kind: &EffectKind) -> Option<Touches>

What dispatching kind may read and change, for a tool’s handler (Tool::footprint); None when it cannot say, such as for arguments that do not parse.

fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption>

The options of kind this handler would leave out when it serves it, with nothing sent: for a model’s handler, what its wire or model cannot honour (DynModel::check). Empty when it leaves nothing out or cannot say, as by default.