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 model-visible tool error — the turn is never panicked by a handler.

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 returned to the model as a tool error.

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.