Struct ToolBuilder 

pub struct ToolBuilder { /* private fields */ }

Fluent builder for defining tools with both schemas and handlers.

ToolBuilder combines tool definitions (sent to the API) with tool handlers (for local execution), similar to the TypeScript/Go SDK patterns.

Example

use modelrelay::{ToolBuilder, ToolCall};
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::json;

#[derive(JsonSchema, Deserialize)]
struct WeatherArgs {
    /// City name
    location: String,
    /// Temperature unit (optional)
    unit: Option<String>,
}

let tools = ToolBuilder::new()
    .add_sync::<WeatherArgs, _>("get_weather", "Get weather for a location", |args, _call| {
        Ok(json!({ "temp": 72, "location": args.location }))
    })
    .add_async::<SearchArgs, _>("search", "Search the web", |args, _call| {
        Box::pin(async move {
            Ok(json!({ "results": ["result1", "result2"] }))
        })
    });

// Extract definitions for API request
let (definitions, registry) = tools.build();

Implementations

impl ToolBuilder

pub fn new() -> Self

Creates a new empty tool builder.

pub fn add_sync<T, F>( self, name: impl Into<String>, description: impl Into<String>, handler: F, ) -> Self

where T: JsonSchema + DeserializeOwned + Send + 'static, F: Fn(T, ToolCall) -> Result<Value, String> + Send + Sync + 'static,

Adds a synchronous tool handler with type-safe arguments.

The argument type must implement JsonSchema (for generating the schema) and DeserializeOwned (for parsing incoming arguments).

Example

use schemars::JsonSchema;
use serde::Deserialize;
use modelrelay::ToolBuilder;

#[derive(JsonSchema, Deserialize)]
struct Args { path: String }

let tools = ToolBuilder::new()
    .add_sync::<Args, _>("read_file", "Read a file", |args, _call| {
        Ok(serde_json::json!({ "content": "file contents" }))
    });

pub fn add_async<T, F>( self, name: impl Into<String>, description: impl Into<String>, handler: F, ) -> Self

where T: JsonSchema + DeserializeOwned + Send + 'static, F: Fn(T, ToolCall) -> BoxFuture<'static, Result<Value, String>> + Send + Sync + 'static,

Adds an asynchronous tool handler with type-safe arguments.

The handler returns a boxed future for async execution.

Example

use schemars::JsonSchema;
use serde::Deserialize;
use modelrelay::ToolBuilder;

#[derive(JsonSchema, Deserialize)]
struct Args { query: String }

let tools = ToolBuilder::new()
    .add_async::<Args>("search", "Search the web", |args, _call| {
        Box::pin(async move {
            Ok(serde_json::json!({ "results": ["result"] }))
        })
    });

pub fn add_raw( self, name: impl Into<String>, description: impl Into<String>, parameters: Option<Value>, handler: ToolHandler, ) -> Self

Adds a raw tool handler without type-safe argument parsing.

Use this when you want to handle argument parsing yourself or need more control over the handler behavior.

pub fn definitions(&self) -> Vec<Tool>

Returns just the tool definitions (for API requests).

pub fn registry(&self) -> &ToolRegistry

Returns just the tool registry (for execution).

pub fn build(self) -> (Vec<Tool>, ToolRegistry)

Consumes the builder and returns both definitions and registry.

This is typically called when passing tools to an agent loop.

Trait Implementations

impl Default for ToolBuilder

fn default() -> Self

Returns the “default value” for a type.