Skip to main content

Tool

agent_engine::tools

Trait Tool 

Source 
pub trait Tool: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters(&self) -> Value;
    fn execute<'life0, 'async_trait>(
        &'life0 self,
        params: Value,
        ctx: ToolContext,
    ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided methods
    fn execute_rich<'life0, 'async_trait>(
        &'life0 self,
        params: Value,
        ctx: ToolContext,
    ) -> Pin<Box<dyn Future<Output = Result<ToolOutput>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn extension_id(&self) -> Option<&str> { ... }
    fn source_operation(&self) -> Option<&str> { ... }
    fn origin(&self) -> ToolOrigin { ... }
    fn effect(&self) -> ToolEffect { ... }
    fn runs_independently(&self) -> bool { ... }
    fn concurrency_key(
        &self,
        _validated_input: &Value,
    ) -> Option<ConcurrencyKey> { ... }
    fn concurrency_key_in(
        &self,
        validated_input: &Value,
        _cwd: Option<&Path>,
    ) -> Option<ConcurrencyKey> { ... }
}
Expand description

The core trait for all tools. Implement this to add a new tool.

Required Methods§

Source

fn name(&self) -> &str

Tool name as it appears in the API (e.g. “bash”, “read”).

Source

fn description(&self) -> &str

Human-readable description sent to the model.

Source

fn parameters(&self) -> Value

JSON Schema for the tool’s parameters.

Source

fn execute<'life0, 'async_trait>( &'life0 self, params: Value, ctx: ToolContext, ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Execute the tool with the given parameters.

Provided Methods§

Source

fn execute_rich<'life0, 'async_trait>( &'life0 self, params: Value, ctx: ToolContext, ) -> Pin<Box<dyn Future<Output = Result<ToolOutput>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Structured variant of Tool::execute. DEFAULTED — existing tools keep returning String via execute and never see this. Tools that need to place non-text content blocks (images) into the model history override this and make execute delegate to it.

RECURSION TRAP: the default delegates to execute. If you make execute delegate here (as ReadTool does) you MUST override this method too, or the pair recurses until the stack blows.

Source

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

Owning extension id for tools registered by an extension. Built-in tools return None.

Source

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

The operation name this tool was registered under by its source (an extension’s own tool name, before the <extension>: runtime prefix), when that differs from Tool::name. Typed metadata for policy that must not depend on the exposed name alone; None when not declared.

Source

fn origin(&self) -> ToolOrigin

Runtime-origin identity used for catalog provenance. Conservative by default: tools that declare nothing are Unknown (fail-closed source trust), and tools that declare an owning extension classify as extension-provided. Built-in implementations override this explicitly.

Source

fn effect(&self) -> ToolEffect

Conservative effect class (Task 24, spec §8.2). The default keeps unknown/dynamic tools NonIdempotent — serialized execution; implementations opt IN to weaker classes explicitly.

Source

fn runs_independently(&self) -> bool

Each call is its own independent actor (a subagent): sibling calls in one batch each get their own scheduler lane and run concurrently, instead of joining the shared serial lane that NonIdempotent tools use. Scheduling only — the effect class, and with it the rule that an interrupted call is never re-run automatically, is unchanged.

Source

fn concurrency_key(&self, _validated_input: &Value) -> Option<ConcurrencyKey>

Key resolution derived from validated input. Serialize explicitly fails closed into the global mutation lane; None is the conservative default for tools with no key support.

Source

fn concurrency_key_in( &self, validated_input: &Value, _cwd: Option<&Path>, ) -> Option<ConcurrencyKey>

Self::concurrency_key for a call made in cwd, the chat’s folder (None: the process folder). The scheduler asks this one. A tool whose key is a path resolves a relative one against cwd, as its execute does, so the key names the file the call will touch; a tool whose key does not depend on the folder has nothing to add.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§