Struct ToolInvocationContext 

pub struct ToolInvocationContext { /* private fields */ }

Context available to local tools that declare caller interaction support.

Examples

use tools_kit::{
    ToolHandlerBackend, Toolset, ToolsetBackend,
    declaration::{ToolInfo, ToolName},
    execution::{ToolHandlerInput, ToolHandlerOutput, ToolInvocation, ToolResult},
    interaction::{ToolInteractionCapabilities, ToolInteractionResponse},
    local::ToolRegistration,
    schema::JsonSchema,
};
let name = ToolName::new("ask")?;
let mut info = ToolInfo::new(
    name.clone(),
    JsonSchema::strict(serde_json::json!({"type":"object"})),
);
info.interactions = ToolInteractionCapabilities { text: true, ..Default::default() };
let registration = ToolRegistration::interactive(info, |_input, context| async move {
    let city = context.request_text("Which city?", false).await?;
    Ok(ToolResult::text(city))
});
let tools = Toolset::local(vec![registration])?;
let observed = async {
    let mut handler = tools.tool_handler(name).await?;
    let pending = handler.step(ToolHandlerInput::Invoke(ToolInvocation { call_id: None, arguments: serde_json::json!({}) })).await?;
    let ToolHandlerOutput::Interaction(request) = pending else { panic!("interaction expected") };
    let reply = ToolInteractionResponse::submit(request.id, serde_json::json!("Chicago"));
    let done = handler.step(ToolHandlerInput::Interaction(reply)).await?;
    assert!(matches!(done, ToolHandlerOutput::Completed(_)));
    Ok::<(), tools_kit::ToolError>(())
}.await;
let cleanup = tools.shutdown().await;
if let Err(error) = &cleanup {
    eprintln!("Cleanup failed: {error}");
}
observed?;
cleanup?;

Implementations

impl ToolInvocationContext

pub async fn request_text( &self, prompt: impl Into<String>, multiline: bool, ) -> Result<String, ToolError>

Requests text from the caller and waits for its resolution.

Returns ToolError::UndeclaredInteraction when the registration did not declare the requested text capability.

Errors

Returns ToolError::UndeclaredInteraction for absent text or multiline capability, ToolError::InvalidInteraction for an invalid reply, or the corresponding decline, cancellation, or closure error.

See crate::local::ToolRegistration::interactive for a complete example.

pub async fn request_form( &self, prompt: impl Into<String>, schema: Value, schema_validation: bool, ) -> Result<Value, ToolError>

Requests a JSON form value from the caller and waits for its resolution.

When schema_validation is true, the submitted object is validated before it is returned. Form replies must be objects even when schema validation is disabled.

Errors

Returns ToolError::UndeclaredInteraction for an absent form capability, validation errors for malformed replies or schemas, or the corresponding decline, cancellation, or closure error.

Examples

use tools_kit::{
    ToolHandlerBackend, Toolset, ToolsetBackend,
    declaration::{ToolInfo, ToolName},
    execution::{ToolHandlerInput, ToolHandlerOutput, ToolInvocation, ToolResult},
    interaction::{ToolInteractionCapabilities, ToolInteractionResponse},
    local::ToolRegistration,
    schema::JsonSchema,
};
let name = ToolName::new("ask")?;
let mut info = ToolInfo::new(
    name.clone(),
    JsonSchema::strict(serde_json::json!({"type":"object"})),
);
info.interactions = ToolInteractionCapabilities { form: true, form_schema_validation: true, ..Default::default() };
let registration = ToolRegistration::interactive(info, |_input, context| async move {
    let city = context.request_form("Which city?", serde_json::json!({"type":"object","required":["city"],"properties":{"city":{"type":"string"}}}), true).await?;
    Ok(ToolResult::json(city))
});
let tools = Toolset::local(vec![registration])?;
let observed = async {
    let mut handler = tools.tool_handler(name).await?;
    let pending = handler.step(ToolHandlerInput::Invoke(ToolInvocation { call_id: None, arguments: serde_json::json!({}) })).await?;
    let ToolHandlerOutput::Interaction(request) = pending else { panic!("interaction expected") };
    let reply = ToolInteractionResponse::submit(request.id, serde_json::json!({"city":"Chicago"}));
    let done = handler.step(ToolHandlerInput::Interaction(reply)).await?;
    let ToolHandlerOutput::Completed(result) = done else { panic!("completion expected") };
    assert!(!result.is_error);
    assert_eq!(result.structured_content, Some(serde_json::json!({"city":"Chicago"})));
    Ok::<(), tools_kit::ToolError>(())
}.await;
let cleanup = tools.shutdown().await;
if let Err(error) = &cleanup {
    eprintln!("Cleanup failed: {error}");
}
observed?;
cleanup?;

Trait Implementations

impl Clone for ToolInvocationContext

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ToolInvocationContext

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

Formats the value using the given formatter.