Struct ToolCallHandle 

pub struct ToolCallHandle<'a, S> { /* private fields */ }

One open tool call.

Created by RunContext::tool_call. TOOL_CALL_START has already gone out; Drop emits TOOL_CALL_END.

Arguments stream as text because providers stream them as text — a partial delta is usually not valid JSON. The handle keeps what it emitted, so parse_args can hand you the finished struct to execute against:

#[derive(Deserialize)]
struct Query { city: String }

let mut call = ctx.tool_call("get_weather")?;
call.args(r#"{"city":"#)?;          // as the provider streams them
call.args(r#""Seoul"}"#)?;
let query: Query = call.parse_args()?;
assert_eq!(query.city, "Seoul");
call.result(r#"{"tempC":21}"#)?;    // emits TOOL_CALL_END then TOOL_CALL_RESULT

Doing the work while the call is open

The handle borrows the run’s event sink and its state, not the run context, so the tool’s own work belongs between the arguments and the result. The protocol treats the STATE_* family as unordered, so a publish inside the brackets is a legal stream — and the one that lets a client watch the call land instead of seeing it land already done:

#[derive(Default, Serialize, Deserialize)]
struct Board { tasks: Vec<String> }

let mut call = ctx.tool_call("add_task")?;
call.args_json(&json!({"title": "ship it"}))?;

call.state_mut().tasks.push("ship it".to_owned());
call.publish_state()?;               // STATE_SNAPSHOT, with the call open

call.result_json(&json!({"ok": true}))?;
assert_eq!(ctx.state().tasks, ["ship it"]);

What the handle still cannot do is open a second message, reasoning block or tool call: it holds no run context to open one with, and the context it came from stays borrowed until it drops.

Implementations

impl<'a, S> ToolCallHandle<'a, S>

pub fn id(&self) -> &ToolCallId

The id every event of this call carries.

pub fn result_message_id(&self) -> &MessageId

The id the result message will carry.

pub fn args(&mut self, delta: impl AsRef<str>) -> Result<()>

Appends a fragment of the argument JSON — TOOL_CALL_ARGS.

pub fn args_json<T: Serialize + ?Sized>(&mut self, value: &T) -> Result<()>

Serializes value and emits it as the call’s arguments in one delta.

pub fn raw_args(&self) -> &str

The argument JSON emitted so far, unparsed.

pub fn parse_args<T: DeserializeOwned>(&self) -> Result<T>

Parses everything emitted through args into T.

Fails while the arguments are still partial, which is the point: call it once the provider has finished streaming them.

pub fn encrypted_value(&mut self, value: impl Into<String>) -> Result<()>

Attaches the provider’s opaque reasoning signature for this call — REASONING_ENCRYPTED_VALUE.

pub fn emit(&mut self, event: Event) -> Result<()>

Emits an unrelated event without closing the call. See MessageHandle::emit.

pub fn end(self) -> Result<()>

Emits TOOL_CALL_END and consumes the handle, leaving the call unanswered.

Use it when the client executes the tool — a front-end tool’s result arrives as a message on the next request, not from here.

pub fn result(self, content: impl Into<String>) -> Result<MessageId>

Emits TOOL_CALL_END then TOOL_CALL_RESULT, and consumes the handle.

Returns the id of the tool message carrying the result.

pub fn result_json<T: Serialize + ?Sized>(self, value: &T) -> Result<MessageId>

Serializes value and reports it as the call’s result.

impl<S: AgentState> ToolCallHandle<'_, S>

The run’s state, reachable while the call is open. Same three methods as on RunContext, forwarded — a tool that changes the state is the ordinary case, and it changes it in the middle of the call.

pub fn state(&self) -> &S

The typed state, as of the last publish.

pub fn state_mut(&mut self) -> &mut S

The typed state, mutably. Nothing is emitted until you call publish_state.

pub fn publish_state(&mut self) -> Result<()>

Publishes whatever state_mut left behind, as a STATE_SNAPSHOT or a STATE_DELTA between this call’s TOOL_CALL_START and its TOOL_CALL_END.

A no-op when nothing changed since the last publish.

Trait Implementations

impl<'a, S: Debug> Debug for ToolCallHandle<'a, S>

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

Formats the value using the given formatter.

impl<S> Drop for ToolCallHandle<'_, S>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.