distri_types/
tool.rs

1use anyhow::Result;
2use std::{collections::HashMap, sync::Arc};
3use tokio::sync::mpsc;
4
5use crate::Part;
6use crate::{
7    ToolCall, ToolDefinition, auth::AuthMetadata, events::AgentEvent, stores::SessionStore,
8};
9
10/// Tool execution context - lighter weight than ExecutorContext
11#[derive(Debug, Clone)]
12pub struct ToolContext {
13    /// Agent ID executing the tool
14    pub agent_id: String,
15    /// Session ID for the current conversation
16    pub session_id: String,
17    /// Task ID for the current task
18    pub task_id: String,
19    /// Run ID for the current execution
20    pub run_id: String,
21    /// Thread ID for conversation grouping
22    pub thread_id: String,
23    /// User ID if available
24    pub user_id: String,
25    /// Session store for persistent state across tool calls
26    pub session_store: Arc<dyn SessionStore>,
27    /// Event sender for emitting events during tool execution
28    pub event_tx: Option<Arc<mpsc::Sender<AgentEvent>>>,
29
30    /// Additional metadata for the tool. Useful in direct inline agent invocation.
31    pub metadata: Option<HashMap<String, serde_json::Value>>,
32}
33
34/// Tool trait for implementing tools that can be called by agents
35#[async_trait::async_trait]
36pub trait Tool: Send + Sync + std::fmt::Debug + std::any::Any {
37    fn get_name(&self) -> String;
38
39    /// Get the tool definition for the LLM
40    fn get_tool_definition(&self) -> ToolDefinition {
41        ToolDefinition {
42            name: self.get_name(),
43            description: self.get_description(),
44            parameters: self.get_parameters(),
45            output_schema: None,
46            examples: self.get_tool_examples(),
47            prompt: self.prompt(),
48        }
49    }
50
51    fn get_parameters(&self) -> serde_json::Value;
52    fn get_description(&self) -> String;
53
54    fn get_tool_examples(&self) -> Option<String> {
55        None
56    }
57
58    /// Optional detailed prompt/instructions for this tool.
59    /// When provided, these instructions are injected into the system prompt
60    /// so the LLM knows HOW to use the tool (not just what parameters it takes).
61    /// This mirrors claude-code's per-tool `prompt()` pattern.
62    fn prompt(&self) -> Option<String> {
63        None
64    }
65
66    /// Check if this tool is external (handled by frontend)
67    fn is_external(&self) -> bool {
68        false // Default to false for built-in tools
69    }
70
71    /// Check if this tool is an MCP tool
72    fn is_mcp(&self) -> bool {
73        false // Default to false for built-in tools
74    }
75
76    fn is_sync(&self) -> bool {
77        false // Default to false for built-in tools
78    }
79
80    fn is_final(&self) -> bool {
81        false // Default to false for built-in tools
82    }
83
84    /// Check if this tool needs ExecutorContext instead of ToolContext
85    fn needs_executor_context(&self) -> bool {
86        false // Default to false - most tools use ToolContext
87    }
88
89    /// Get authentication metadata for this tool
90    fn get_auth_metadata(&self) -> Option<Box<dyn AuthMetadata>> {
91        None // Default to no authentication required
92    }
93
94    /// Get the plugin name this tool belongs to (nullable)
95    /// If this returns Some, the tool is part of a plugin
96    /// If None, the tool is standalone
97    fn get_plugin_name(&self) -> Option<String> {
98        None // Default to standalone tool
99    }
100
101    /// Execute the tool with given arguments, returning content parts
102    async fn execute(
103        &self,
104        tool_call: ToolCall,
105        context: Arc<ToolContext>,
106    ) -> Result<Vec<Part>, anyhow::Error>;
107
108    /// Synchronous execution of the tool, returning content parts (default unsupported)
109    fn execute_sync(
110        &self,
111        _tool_call: ToolCall,
112        _context: Arc<ToolContext>,
113    ) -> Result<Vec<Part>, anyhow::Error> {
114        Err(anyhow::anyhow!("Sync execution not supported"))
115    }
116}
distri_types/tool.rs

distri_types/
tool.rs
