Skip to main content

Interface: TokenHandlers

Defined in: packages/core/src/types.ts:372

Object-based token handlers for better ergonomics and type safety Each handler is optional and receives strongly-typed event data

Handlers are organized into two categories:

  • STREAMING EVENTS: Real-time events during execution (use these for live updates)
  • FINAL EVENTS: Completion events when operations finish (also available via process() return value)

Example​

const handlers: TokenHandlers = {
  // Streaming events (real-time)
  onTextDelta(botName, event) {
    process.stdout.write(event.content);  // Stream as it generates
  },
  onToolExecutionStart(botName, event) {
    console.log(`${botName} starting ${event.toolName}`);
  },
  // Final events (when complete)
  onToolExecutionOutput(botName, event) {
    console.log(`Result: ${event.result}`);
  }
  // Other handlers are optional - omit what you don't need
};

await bot.process(input, { onToken: handlers });

Properties​

onError?​

optional onError?: (botName, event) => void

Defined in: packages/core/src/types.ts:417

Called when an error occurs

Parameters​

botName​

string

event​
error​

Error | { message: string; name?: string; stack?: string; } = ...

type​

"error" = ...

Returns​

void

onReasoning?​

optional onReasoning?: (botName, event) => void

Defined in: packages/core/src/types.ts:414

Called when reasoning content is generated

Parameters​

botName​

string

event​
content​

string = ...

type​

"reasoning" = ...

Returns​

void

onStructuredOutputDelta?​

optional onStructuredOutputDelta?: (botName, event) => void

Defined in: packages/core/src/types.ts:383

Called for each structured output token during streaming

Parameters​

botName​

string

event​
content​

string = ...

type​

"structured_output_delta" = ...

Returns​

void

onTextDelta?​

optional onTextDelta?: (botName, event) => void

Defined in: packages/core/src/types.ts:380

Called for each text token during streaming

Parameters​

botName​

string

event​
content​

string = ...

type​

"text_delta" = ...

Returns​

void

onToolCallArgumentsDelta?​

optional onToolCallArgumentsDelta?: (botName, event) => void

Defined in: packages/core/src/types.ts:390

Called for each chunk of tool arguments as LLM streams them

Parameters​

botName​

string

event​
argumentsDelta​

string = ...

id​

string = ...

type​

"tool_call_arguments_delta" = ...

Returns​

void

onToolCallStreamComplete?​

optional onToolCallStreamComplete?: (botName, event) => void

Defined in: packages/core/src/types.ts:393

Called when LLM finishes streaming a tool call (before execution)

Parameters​

botName​

string

event​
arguments​

unknown = ...

id​

string = ...

toolName​

string = ...

type​

"tool_call_stream_complete" = ...

Returns​

void

onToolCallStreamStart?​

optional onToolCallStreamStart?: (botName, event) => void

Defined in: packages/core/src/types.ts:387

Called when LLM starts streaming a tool call

Parameters​

botName​

string

event​
id​

string = ...

toolName​

string = ...

type​

"tool_call_stream_start" = ...

Returns​

void

onToolCallValidationError?​

optional onToolCallValidationError?: (botName, event) => void

Defined in: packages/core/src/types.ts:411

Called when tool arguments fail validation

Parameters​

botName​

string

event​
receivedArguments​

unknown = ...

toolName​

string = ...

type​

"tool_validation_error" = ...

validationErrors​

unknown = ...

Returns​

void

onToolExecutionOutput?​

optional onToolExecutionOutput?: (botName, event) => void

Defined in: packages/core/src/types.ts:408

Called when tool execution completes with output

Parameters​

botName​

string

event​
arguments?​

unknown = ...

error?​

string = ...

errorDetail?​

{ code?: string; message: string; type?: string; } = ...

errorDetail.code?​

string = ...

errorDetail.message​

string = ...

errorDetail.type?​

string = ...

id​

string = ...

result​

unknown = ...

toolName​

string = ...

type​

"tool_execution_output" = ...

Returns​

void

onToolExecutionStart?​

optional onToolExecutionStart?: (botName, event) => void

Defined in: packages/core/src/types.ts:397

Called when tool execution starts

Parameters​

botName​

string

event​
arguments​

unknown = ...

id​

string = ...

toolName​

string = ...

type​

"tool_execution_start" = ...

Returns​

void

onToolExecutionStream?​

optional onToolExecutionStream?: (botName, event) => void

Defined in: packages/core/src/types.ts:400

Called when tool execution emits nested streaming events (e.g., from child bots)

Parameters​

botName​

string

event​

ToolExecutionStreamEvent

Returns​

void