pub trait AgentTool: Send + Sync {
// Required methods
fn name(&self) -> &str;
fn label(&self) -> &str;
fn description(&self) -> &str;
fn parameters_schema(&self) -> Value;
fn execute<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
tool_call_id: &'life1 str,
params: Value,
signal: Option<Receiver<()>>,
ctx: &'life2 ToolContext,
) -> Pin<Box<dyn Future<Output = Result<AgentToolResult, String>> + Send + 'async_trait>>
where 'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait;
// Provided methods
fn essential(&self) -> bool { ... }
fn on_progress(&self, _callback: Arc<dyn Fn(String) + Sync + Send>) { ... }
fn on_structured_progress(
&self,
_callback: Arc<dyn Fn(ToolProgress) + Sync + Send>,
) { ... }
fn render_call(&self, _params: &Value) -> Option<RenderOutput> { ... }
fn render_result(&self, _result: &AgentToolResult) -> Option<RenderOutput> { ... }
fn execution_mode(&self) -> ToolExecutionMode { ... }
fn to_definition(&self) -> ToolDefinition { ... }
}Expand description
Core trait for all agent tools
Required Methods§
Sourcefn description(&self) -> &str
fn description(&self) -> &str
Description for the model
Sourcefn parameters_schema(&self) -> Value
fn parameters_schema(&self) -> Value
JSON Schema for parameters
Sourcefn execute<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
tool_call_id: &'life1 str,
params: Value,
signal: Option<Receiver<()>>,
ctx: &'life2 ToolContext,
) -> Pin<Box<dyn Future<Output = Result<AgentToolResult, String>> + Send + 'async_trait>>where
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait,
fn execute<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
tool_call_id: &'life1 str,
params: Value,
signal: Option<Receiver<()>>,
ctx: &'life2 ToolContext,
) -> Pin<Box<dyn Future<Output = Result<AgentToolResult, String>> + Send + 'async_trait>>where
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Self: 'async_trait,
Execute the tool with the given tool call ID and parameters.
The ctx parameter provides workspace information. File tools should
use ctx.root() to get the effective directory. Custom tools can use
ctx.workspace_dir for workspace-relative operations.
§Examples
use oxi_agent::{AgentTool, AgentToolResult, ToolContext};
use serde_json::json;
use async_trait::async_trait;
struct MyTool;
#[async_trait]
impl AgentTool for MyTool {
fn name(&self) -> &str { "my_tool" }
fn label(&self) -> &str { "My Tool" }
fn description(&self) -> &str { "A custom tool" }
fn parameters_schema(&self) -> Value { json!({
"type": "object",
"properties": {}
}) }
async fn execute(&self, tool_call_id: &str, params: Value, _signal: Option<oneshot::Receiver<()>>, ctx: &ToolContext) -> Result<AgentToolResult, String> {
println!("Tool '{}' called with params: {:?}, workspace: {:?}", tool_call_id, params, ctx.workspace_dir);
Ok(AgentToolResult::success("Done!"))
}
}Provided Methods§
Sourcefn essential(&self) -> bool
fn essential(&self) -> bool
Whether this tool is essential (cannot be disabled). Essential tools: read, write, edit, bash, grep, find, ls Optional tools: web_search, github, subagent, etc.
Sourcefn on_progress(&self, _callback: Arc<dyn Fn(String) + Sync + Send>)
fn on_progress(&self, _callback: Arc<dyn Fn(String) + Sync + Send>)
Called with progress updates during execution. Tools can override this to emit streaming updates.
Sourcefn on_structured_progress(
&self,
_callback: Arc<dyn Fn(ToolProgress) + Sync + Send>,
)
fn on_structured_progress( &self, _callback: Arc<dyn Fn(ToolProgress) + Sync + Send>, )
Structured progress callback for streaming tool execution updates. Default implementation is no-op. Override in tools that support structured progress (e.g., BashTool for partial output streaming).
Sourcefn render_call(&self, _params: &Value) -> Option<RenderOutput>
fn render_call(&self, _params: &Value) -> Option<RenderOutput>
Custom rendering for tool call (TUI visualization). Return None to use the default tool_renderer.rs formatter.
Sourcefn render_result(&self, _result: &AgentToolResult) -> Option<RenderOutput>
fn render_result(&self, _result: &AgentToolResult) -> Option<RenderOutput>
Custom rendering for tool result (TUI visualization). Return None to use the default tool_renderer.rs formatter.
Sourcefn execution_mode(&self) -> ToolExecutionMode
fn execution_mode(&self) -> ToolExecutionMode
Execution mode for parallel safety. Defaults to ParallelSafe. Override for file-mutating or sequential tools.
Sourcefn to_definition(&self) -> ToolDefinition
fn to_definition(&self) -> ToolDefinition
Convert to ToolDefinition
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".