Struct StatefulTool 

pub struct StatefulTool<S>
where
    S: Send + Sync + 'static,
{ /* private fields */ }

Available on crate feature tools only.

A generic tool wrapper that manages shared state for stateful closures.

StatefulTool<S> accepts an Arc<S> and a handler closure that receives the state alongside the tool context and arguments. The Arc<S> is cloned (cheap reference count bump) on each invocation, so all executions share the same underlying state.

Example

use adk_tool::StatefulTool;
use adk_core::{ToolContext, Result};
use serde_json::{json, Value};
use std::sync::Arc;
use tokio::sync::RwLock;

struct Counter { count: RwLock<u64> }

let state = Arc::new(Counter { count: RwLock::new(0) });

let tool = StatefulTool::new(
    "increment",
    "Increment a counter",
    state,
    |s, _ctx, _args| async move {
        let mut count = s.count.write().await;
        *count += 1;
        Ok(json!({ "count": *count }))
    },
);

Implementations

impl<S> StatefulTool<S>

where S: Send + Sync + 'static,

pub fn new<F, Fut>( name: impl Into<String>, description: impl Into<String>, state: Arc<S>, handler: F, ) -> StatefulTool<S>

where F: Fn(Arc<S>, Arc<dyn ToolContext>, Value) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<Value, AdkError>> + Send + 'static,

Create a new stateful tool.

Arguments

• name - Tool name exposed to the LLM
• description - Human-readable description of what the tool does
• state - Shared state wrapped in Arc<S>
• handler - Async closure receiving (Arc<S>, Arc<dyn ToolContext>, Value)

pub fn with_long_running(self, long_running: bool) -> StatefulTool<S>

Mark this tool as long-running (prevents duplicate invocations).

pub fn with_read_only(self, read_only: bool) -> StatefulTool<S>

Mark this tool as read-only (safe for parallel dispatch).

pub fn with_concurrency_safe(self, concurrency_safe: bool) -> StatefulTool<S>

Mark this tool as concurrency-safe (can run in parallel with other tools).

pub fn with_parameters_schema<T>(self) -> StatefulTool<S>

where T: JsonSchema + Serialize,

Derive the parameters JSON Schema from a type implementing JsonSchema.

pub fn with_response_schema<T>(self) -> StatefulTool<S>

where T: JsonSchema + Serialize,

Derive the response JSON Schema from a type implementing JsonSchema.

pub fn with_scopes(self, scopes: &[&'static str]) -> StatefulTool<S>

Declare the scopes required to execute this tool.

When set, the framework will enforce that the calling user possesses all listed scopes before dispatching execute().

pub fn parameters_schema(&self) -> Option<&Value>

Get the parameters schema, if set.

pub fn response_schema(&self) -> Option<&Value>

Get the response schema, if set.

Trait Implementations

impl<S> Tool for StatefulTool<S>

where S: Send + Sync + 'static,

fn name(&self) -> &str

Returns the unique name of this tool.

fn description(&self) -> &str

Returns a human-readable description of what this tool does.

fn enhanced_description(&self) -> String

Returns an enhanced description that may include additional notes. For long-running tools, this includes a warning not to call the tool again if it has already returned a pending status. Default implementation returns the base description.

fn is_long_running(&self) -> bool

Indicates whether the tool is a long-running operation. Long-running tools typically return a task ID immediately and complete the operation asynchronously.

fn is_read_only(&self) -> bool

Indicates whether this tool performs no side effects.

fn is_concurrency_safe(&self) -> bool

Indicates whether this tool is safe for concurrent execution.

fn parameters_schema(&self) -> Option<Value>

Returns the JSON Schema for this tool’s parameters, if any.

fn response_schema(&self) -> Option<Value>

Returns the JSON Schema for this tool’s response, if any.

fn required_scopes(&self) -> &[&str]

Returns the scopes required to execute this tool.

fn execute<'life0, 'async_trait>( &'life0 self, ctx: Arc<dyn ToolContext>, args: Value, ) -> Pin<Box<dyn Future<Output = Result<Value, AdkError>> + Send + 'async_trait>>

where 'life0: 'async_trait, StatefulTool<S>: 'async_trait,

Executes the tool with the given context and arguments.

fn declaration(&self) -> Value

Returns the tool declaration that should be exposed to model providers.

fn is_builtin(&self) -> bool

Indicates whether this tool is a built-in server-side tool (e.g., google_search, url_context).