ToolExecutionContext | TanStack AI Docs

type ToolExecutionContext<TContext> = RuntimeContextField<TContext> & object;

type ToolExecutionContext<TContext> = RuntimeContextField<TContext> & object;

Defined in: packages/ai/src/types.ts:872

Context passed to tool execute functions, providing capabilities like emitting custom events during execution.

Type Declaration

abortSignal?

optional abortSignal?: AbortSignal;

optional abortSignal?: AbortSignal;

Abort signal for the current chat run. Aborts when the run's abortController fires (or middleware aborts). Long-running tools — e.g. MCP callTool — should forward this to cancel in-flight work.

detach?

optional detach?: (work) => Promise<string>;

optional detach?: (work) => Promise<string>;

Set when the host can move this call to the background. Pass it the work of the call, and race the two promises. It resolves to a short note for the model when the user moves the call. The work keeps running, and the host tells the model its result when it ends. chat() does not set it: a host wraps the tool's execute to add it. The note is a string. An object outputSchema rejects it. A string schema, or no schema, accepts it.

Parameters

work

Promise<unknown>

Returns

Promise<string>

Example

const work = runJob(args)
return context?.detach ? Promise.race([work, context.detach(work)]) : work

const work = runJob(args)
return context?.detach ? Promise.race([work, context.detach(work)]) : work

emitCustomEvent

emitCustomEvent: (eventName, value, options?) => void;

emitCustomEvent: (eventName, value, options?) => void;

Emit a custom event during tool execution. Events are streamed to the client in real-time as AG-UI CUSTOM events.

const tool = toolDefinition({ ... }).server(async (args, context) => {
  context?.emitCustomEvent('progress', { step: 1, total: 3 })
  // ... do work ...
  context?.emitCustomEvent('progress', { step: 2, total: 3 })
  // ... do more work ...
  return result
})

const tool = toolDefinition({ ... }).server(async (args, context) => {
  context?.emitCustomEvent('progress', { step: 1, total: 3 })
  // ... do work ...
  context?.emitCustomEvent('progress', { step: 2, total: 3 })
  // ... do more work ...
  return result
})

inputResponse?

optional inputResponse?: ToolInputResponse;

optional inputResponse?: ToolInputResponse;

The answer to the input request that this tool call raised in the previous run. It is set only when the run resumes an mcp_input interrupt for this tool call.

toolCallId?

optional toolCallId?: string;

optional toolCallId?: string;

The ID of the tool call being executed

Type Parameters

TContext

TContext = unknown