Struct ToolContext 

pub struct ToolContext { /* private fields */ }

Context passed to Rust tools during dispatch, mirroring the Python SDK’s ToolContext.

Provides access to the current conversation ID, a shared key-value state store that persists across tool calls within the same agent turn, and an idle flag.

The state is backed by Arc<RwLock<HashMap>> so it can be cheaply cloned and shared across concurrent tool invocations. Reads acquire a shared lock; only writes take an exclusive lock.

get_state vs set_state error handling

These two methods intentionally handle mutex poisoning differently:

• get_state acquires a read lock and returns the caller-supplied default when the lock is poisoned. Reads are best-effort — a missing value is indistinguishable from a default, so returning default keeps the tool running without surfacing infrastructure errors to the model.

• set_state acquires a write lock and returns Err when the lock is poisoned. Writes that silently vanish can cause subtle logic bugs, so callers must handle the failure explicitly.

Typed extensions

In addition to the string-keyed JSON state, ToolContext supports typed extensions via set_ext / get_ext. These use std::any::Any under the hood and are keyed by TypeId, so callers store and retrieve strongly-typed values (typically Arc<T>) without serialization.

use std::sync::Arc;

use llm_tool::ToolContext;

struct MyState {
    session_dir: String,
}

let ctx = ToolContext::new(None);
ctx.set_ext(Arc::new(MyState {
    session_dir: "/tmp".into(),
}));

let state: Arc<MyState> = ctx.get_ext::<Arc<MyState>>().unwrap();
assert_eq!(state.session_dir, "/tmp");

Implementations

impl ToolContext

pub fn new(conversation_id: Option<String>) -> Self

Create a new context with the given conversation ID.

pub fn with_shared_state( conversation_id: Option<String>, state: Arc<RwLock<HashMap<String, Value>>>, ) -> Self

Create a context that shares an externally-provided state map.

Use this when multiple ToolContext instances (e.g. successive tool calls within the same agent) must read/write the same state store.

pub fn conversation_id(&self) -> Option<&str>

Return the conversation ID, if one has been set.

pub fn get_state(&self, key: &str, default: Value) -> Value

Retrieve a value from the shared state, returning default if the key is absent or the lock is poisoned.

This method never fails — on a poisoned lock it logs a warning and returns default. See the struct-level docs for rationale.

pub fn set_state(&self, key: &str, value: Value) -> Result<(), ToolError>

Insert or update a value in the shared state.

Unlike get_state, this method returns Err on a poisoned lock because silently dropping a write can cause subtle bugs. See the struct-level docs for rationale.

Errors

Returns ToolError if the lock is poisoned.

pub const fn is_idle(&self) -> bool

Whether the agent is currently idle.

pub fn set_ext<T: Send + Sync + 'static>(&self, value: T)

Store a typed value in the extensions map.

Values are keyed by TypeId, so each concrete type can only appear once. Typically used to store Arc<T> for shared, cloneable access.

Panics

Panics if the extensions RwLock is poisoned (indicates a prior panic).

pub fn get_ext<T: Clone + Send + Sync + 'static>(&self) -> Option<T>

Retrieve a clone of a typed value from the extensions map.

Returns None if no value of type T has been stored via set_ext.

Panics

Panics if the extensions RwLock is poisoned (indicates a prior panic).