motosan-agent-tool

Shared AI agent tool kit — Rust, Python, and TypeScript. Provides the core Tool trait, registry, and 18 feature-gated built-in tools used by motosan-chat and crucible-agent.

Quick Start

Rust

use motosan_agent_tool::{Tool, ToolDef, ToolResult, ToolContext, ToolRegistry};
use serde_json::json;
use std::sync::Arc;

// Implement a tool
struct MyTool;

impl Tool for MyTool {
    fn def(&self) -> ToolDef {
        ToolDef {
            name: "my_tool".into(),
            description: "Does something useful".into(),
            input_schema: json!({
                "type": "object",
                "properties": {
                    "query": { "type": "string" }
                },
                "required": ["query"]
            }),
        }
    }

    fn call(
        &self,
        args: serde_json::Value,
        _ctx: &ToolContext,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = ToolResult> + Send + '_>> {
        Box::pin(async move {
            let query = args["query"].as_str().unwrap_or("");
            ToolResult::text(format!("Result for: {query}"))
        })
    }
}

// Register and use
#[tokio::main]
async fn main() {
    let registry = ToolRegistry::new();
    registry.register(Arc::new(MyTool)).await;

    let tool = registry.get("my_tool").await.unwrap();
    let ctx = ToolContext::new("user-1", "my-app");
    let result = tool.call(json!({"query": "hello"}), &ctx).await;
    println!("{:?}", result.as_text());
}

Python

from motosan_agent_tool import tool, ToolRegistry

@tool(description="Greet someone")
def greet(name: str) -> str:
    return f"Hello, {name}!"

registry = ToolRegistry()
registry.register(greet)

Design

This crate unifies the tool interfaces of motosan-chat and crucible-agent:

• ToolDef — schema validation (type checking, enum checking, required fields)
• ToolResult — typed content (Text | Json) + optional metadata (citation, duration_ms)
• ToolContext — common fields (caller_id, platform, cwd) + extensible extra map
• ToolRegistry — thread-safe async tool storage

Built-in Tools (Rust)

All tools are feature-gated. Enable individually or use all_tools to enable all.

# Enable specific tools
[dependencies]
motosan-agent-tool = { version = "0.3", features = ["datetime", "web_search"] }

# Or enable all
motosan-agent-tool = { version = "0.3", features = ["all_tools"] }

Multi-language Support

All three packages share the same API surface: Tool, ToolDef, ToolResult, ToolContent, ToolContext, ToolRegistry, ToolError.

The Python package also provides FunctionTool and a @tool decorator for defining tools from plain functions.

License

MIT