Struct FunctionTool 

pub struct FunctionTool { /* private fields */ }

A custom agent tool backed by an async function or closure.

Construct one with FunctionTool::new and hand it to AgentBuilder::tool. The handler is invoked with the model’s call arguments deserialized into a serde_json::Value and returns any IntoToolResult. A returned Err becomes a redacted internal error — the turn is never panicked by a handler. Return ToolResponse::error from the Ok path for errors that are safe to show to the model.

The Err channel is redacted because a handler’s error text is written against the host — a path, a query, a connection string — and the model is an untrusted reader of anything it is shown. The full error is still logged with the tool name and call id, so nothing is lost for the developer. #[everruns::tool] is unaffected: it maps a function’s own Err to a model-visible tool error before it reaches this channel, and reserves this channel for failures the model did not cause.

A FunctionTool is cheap to clone (the handler is reference-counted) and is Send + Sync, so the same tool can execute calls concurrently.

Implementations

impl FunctionTool

pub fn new<F, Fut, T, E>( name: impl Into<String>, description: impl Into<String>, json_schema: Value, handler: F, ) -> Self

where F: Fn(Value) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<T, E>> + Send + 'static, T: IntoToolResult + 'static, E: Display + 'static,

Wrap an async handler as a callable tool.

• name is the identifier the model calls (validated at Agent::build).
• description tells the model when to use the tool.
• json_schema is the JSON Schema for the tool’s arguments (validated at build time).
• handler is an async Fn(serde_json::Value) -> Result<T, E> where T: IntoToolResult (a Value, a String, or a ToolResponse) and E: Display. On Err, the error’s Display text is retained for internal diagnostics but redacted from the model-facing tool result.

pub fn name(&self) -> &str

The tool’s name (the identifier the model calls).

Trait Implementations

impl Clone for FunctionTool

fn clone(&self) -> FunctionTool

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FunctionTool

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl IntoTool for FunctionTool

fn into_tool(self) -> Tool

Convert self into a Tool.

impl Tool for FunctionTool

fn name(&self) -> &str

Returns the tool’s unique name.

fn description(&self) -> &str

Returns a description of what the tool does.

fn parameters_schema(&self) -> Value

Returns the JSON schema for the tool’s parameters.

fn execute<'life0, 'async_trait>( &'life0 self, arguments: Value, ) -> Pin<Box<dyn Future<Output = ToolExecutionResult> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Execute the tool with the given arguments.

fn display_name(&self) -> Option<&str>

Returns a human-readable display name for UI rendering.

fn execute_with_context<'life0, 'life1, 'async_trait>( &'life0 self, arguments: Value, _context: &'life1 ToolContext, ) -> Pin<Box<dyn Future<Output = ToolExecutionResult> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Execute the tool with context.

fn requires_context(&self) -> bool

Returns true if this tool requires context for execution.

fn required_context_services(&self) -> &'static [ToolContextService]

Runtime services that must be present before this tool can be exposed.

fn policy(&self) -> ToolPolicy

Returns the tool policy (auto or requires_approval).

fn hints(&self) -> ToolHints

Returns semantic hints describing the tool’s behavioral properties.

fn narrate( &self, _tool_call: &ToolCall, _phase: ToolNarrationPhase, _locale: Option<&str>, _ctx: ToolNarrationContext<'_>, ) -> Option<String>

Returns backend-authored narration for a call to this tool, e.g. “Read AGENTS.md”.

fn as_background_executable(&self) -> Option<&dyn BackgroundExecutableTool>

Returns native background execution support when this tool opts into detached execution via hints().supports_background.

fn deferrable_policy(&self) -> DeferrablePolicy

Deferral policy for progressive tool-schema disclosure (tool search). Hot-path or “consult-first” tools can return DeferrablePolicy::Never to always keep their full schema directly callable. Defaults to DeferrablePolicy::Automatic.

fn to_definition(&self) -> ToolDefinition

Convert this tool to a ToolDefinition for the agent config.