Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tools

Tools give LLMs the ability to take actions in the world -- calling APIs, querying databases, performing calculations, or any other side effect. Synaptic provides a complete tool system built around the Tool trait defined in synaptic-core.

Key Components

ComponentCrateDescription
Tool traitsynaptic-coreThe interface every tool must implement: name(), description(), and call()
ToolRegistrysynaptic-toolsThread-safe collection of registered tools (Arc<RwLock<HashMap>>)
SerialToolExecutorsynaptic-toolsDispatches tool calls by name through the registry
ToolNodesynaptic-graphGraph node that executes tool calls from AI messages in a state machine workflow
ToolDefinitionsynaptic-coreSchema description sent to the model so it knows what tools are available
ToolChoicesynaptic-coreControls whether and how the model selects tools

How It Works

  1. You define tools using the #[tool] macro (or by implementing the Tool trait manually).
  2. Register them in a ToolRegistry.
  3. Convert them to ToolDefinition values and attach them to a ChatRequest so the model knows what tools are available.
  4. When the model responds with ToolCall entries, dispatch them through SerialToolExecutor to get results.
  5. Send the results back to the model as Message::tool(...) messages to continue the conversation.

Quick Example

use serde_json::{json, Value};
use synaptic::macros::tool;
use synaptic::core::SynapticError;
use synaptic::tools::{ToolRegistry, SerialToolExecutor};

/// Add two numbers.
#[tool]
async fn add(
    /// First number
    a: f64,
    /// Second number
    b: f64,
) -> Result<Value, SynapticError> {
    Ok(json!({"result": a + b}))
}

let registry = ToolRegistry::new();
registry.register(add())?;  // add() returns Arc<dyn Tool>

let executor = SerialToolExecutor::new(registry);
let result = executor.execute("add", json!({"a": 3, "b": 4})).await?;
assert_eq!(result, json!({"result": 7.0}));

Sub-Pages