pub trait AgentTool: Send + Sync {
Show 16 methods
// 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_browse_progress(
&self,
_callback: Arc<dyn Fn(BrowseProgress) + Sync + Send>,
) { ... }
fn render_call(&self, _params: &Value) -> Option<RenderOutput> { ... }
fn render_result(&self, _result: &AgentToolResult) -> Option<RenderOutput> { ... }
fn intent(&self) -> Option<&str> { ... }
fn execution_mode(&self) -> ToolExecutionMode { ... }
fn tool_tier(&self) -> ToolTier { ... }
fn current_tab_id(&self) -> Option<Uuid> { ... }
fn set_tab_id_slot(&self, _slot: Arc<Mutex<RawMutex, Option<Uuid>>>) { ... }
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;
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_browse_progress(
&self,
_callback: Arc<dyn Fn(BrowseProgress) + Sync + Send>,
)
fn on_browse_progress( &self, _callback: Arc<dyn Fn(BrowseProgress) + Sync + Send>, )
Structured browse progress callback for browser tool context enrichment.
Default implementation is no-op. Only browse tools override this to
register a callback that enriches ToolCallContext with structured
data from BrowseProgress events.
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 intent(&self) -> Option<&str>
fn intent(&self) -> Option<&str>
Intent trace — a concise description of what this tool does.
Returned value is included in ToolExecutionStart / ToolExecutionEnd
events so the agent loop can surface intent to users or telemetry.
Default None (no intent tracing).
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 tool_tier(&self) -> ToolTier
fn tool_tier(&self) -> ToolTier
Risk tier for approval gating.
Read— no side effects (lookup, search, inspection).Write— mutates data (creates, edits, commits).Exec— arbitrary side effects (shell, eval, network).
Default: Exec (safest default — requires explicit opt-down).
Sourcefn current_tab_id(&self) -> Option<Uuid>
fn current_tab_id(&self) -> Option<Uuid>
Return the current active tab ID, if this tool manages browser tabs.
Defaults to None. Browser tools override this to return the tab ID
of the currently-open tab during execution, so the agent loop can
populate ToolExecutionUpdate.tab_id.
Sourcefn set_tab_id_slot(&self, _slot: Arc<Mutex<RawMutex, Option<Uuid>>>)
fn set_tab_id_slot(&self, _slot: Arc<Mutex<RawMutex, Option<Uuid>>>)
Receive a shared slot where the tool can write the current tab ID.
The agent loop creates the slot and passes it before on_progress;
the tool writes Some(tab_id) when it opens a tab and None when
it closes it. Defaults to a no-op — only tab-aware tools override.
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".