Skip to main content

Interface: ToolExecutionOptions

Defined in: packages/core/src/utils/tools.ts:60

Tool execution context (AI SDK v6 pattern)

Extended options passed to tool functions during execution. Includes the original ProcessOptions plus tool-specific context.

Example​

const myTool = defineZodTool({
  name: 'my_tool',
  description: 'A tool with context',
  inputSchema: z.object({ data: z.string() }),
  execute: async (params, options) => {
    console.log('Tool call ID:', options?.toolCallId);
    console.log('Message history:', options?.messages?.length);
    return { processed: params.data };
  },
});

Extends​

Properties​

abortSignal?​

optional abortSignal?: AbortSignal

Defined in: packages/core/src/utils/tools.ts:66

Abort signal for cancellation

conversationHistory?​

optional conversationHistory?: object[]

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

Conversation history for multi-turn conversations (uses OpenAI ChatMessage format from providers)

content​

content: string | MessageContentBlock[]

role​

role: "system" | "user" | "assistant" | "tool"

tool_call_id?​

optional tool_call_id?: string

tool_calls?​

optional tool_calls?: object[]

Inherited from​

ProcessOptions.conversationHistory

enableCaching?​

optional enableCaching?: boolean

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

Enable prompt caching for multi-agent pipelines. When true, each agent's system message gets cache control markers, allowing shared document context to be cached across parallel agent calls.

Especially beneficial for extraction pipelines where multiple agents process the same document simultaneously — cached reads cost only 10% (Anthropic) or 50% (OpenAI) of normal input price.

Inherited from​

ProcessOptions.enableCaching

extraVars?​

optional extraVars?: Record<string, unknown>

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

Extra variable bindings injected at process-time (used by BAL map/for iterators).

Inherited from​

ProcessOptions.extraVars

hooks?​

optional hooks?: ProcessHooks

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

Per-step lifecycle hooks. Awaitable — the runner awaits each hook before proceeding, so persistence can land before the next step runs.

For single-step Processables (e.g. a lone Baleybot), hooks fire around the whole invocation. For multi-step Processables (pipeline, graph, ParallelMerge), they fire per step with the appropriate nodeId / nodeLabel.

Zero-cost when unset: the runner skips event construction entirely if hooks is absent AND no subscription is active.

See ProcessHooks in ./graph/types.ts for the full callback shape and ordering contract.

Inherited from​

ProcessOptions.hooks

hooksAreFatal?​

optional hooksAreFatal?: boolean

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

If true, a throwing hook rejects the run. Default (false) logs the error and continues execution — observability should not be able to break a pipeline by accident.

Inherited from​

ProcessOptions.hooksAreFatal

maxTokens?​

optional maxTokens?: number

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

Override maxTokens for this call only. Takes precedence over construction-time maxTokens.

Inherited from​

ProcessOptions.maxTokens

messages?​

optional messages?: ChatMessage[]

Defined in: packages/core/src/utils/tools.ts:64

Current message history (for context-aware tools)

model?​

optional model?: string | ModelConfig

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

Override the model for this call only. Takes precedence over construction-time model.

Inherited from​

ProcessOptions.model

onApprovalRequired?​

optional onApprovalRequired?: (botName, toolCall, toolDefinition) => Promise<ToolApprovalResult>

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

Request approval for individual tool calls (v6 pattern)

Called when a tool has requiresApproval: true or returns true from its requiresApproval function. This is called per-tool, not per-batch.

Parameters​

botName​

string

toolCall​

ToolCall

toolDefinition​

ZodToolDefinition<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>, unknown>

Returns​

Promise<ToolApprovalResult>

Example​

const bot = new Baleybot({
  name: 'bot',
  goal: 'Help with files',
  tools: {
    deleteFile: defineZodTool({
      name: 'delete_file',
      description: 'Delete a file',
      inputSchema: z.object({ path: z.string() }),
      requiresApproval: true,  // Always require approval
      execute: async ({ path }) => { ... },
    }),
  },
});

await bot.process('Delete temp.txt', {
  onApprovalRequired: async (botName, toolCall, toolDef) => {
    // Show approval UI
    const approved = await showApprovalDialog(toolCall);
    return approved
      ? { approved: true }
      : { approved: false, reason: 'User cancelled' };
  },
});

Inherited from​

ProcessOptions.onApprovalRequired

onComplete?​

optional onComplete?: (botName, result) => void

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

Called when processing completes with final result

Note: You can also get the final result from process() return value. This callback is provided for convenience when you need both streaming and completion notification.

Parameters​

botName​

string

result​

unknown

Returns​

void

Inherited from​

ProcessOptions.onComplete

onError?​

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

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

Parameters​

botName​

string

error​

Error

Returns​

void

Inherited from​

ProcessOptions.onError

onStart?​

optional onStart?: (botName) => void

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

Parameters​

botName​

string

Returns​

void

Inherited from​

ProcessOptions.onStart

onToken?​

optional onToken?: TokenHandlers | ((botName, event) => void)

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

Streaming event handlers - receive events in real-time during execution

You can use BOTH streaming events AND final results together:

  • Streaming events: Provide onToken handlers to receive real-time updates via callbacks
  • Final result: Also available when process() Promise resolves (see return value)

Accepts either:

  • A callback function that receives all events
  • An object with specific handlers for each event type (recommended for type safety)

Examples​

// Stream events in real-time AND get final result
const result = await bot.process(input, {
  onToken: {
    // Real-time streaming events
    onTextDelta(botName, event) {
      process.stdout.write(event.content);  // Stream as it generates
    },
    onToolExecutionStart(botName, event) {
      console.log(`🔧 ${event.toolName} starting...`);  // Real-time tool status
    },
    onToolExecutionOutput(botName, event) {
      console.log(`✅ Tool result:`, event.result);  // Final tool result event
    },
    onToolExecutionStream(botName, event) {
      // Nested streaming from child bots
      const nested = event.nestedEvent;
      if (nested.type === 'text_delta') {
        process.stdout.write(nested.content);  // Child bot streaming
      }
    }
  }
});

// Final result available when Promise resolves
console.log('Final response:', result);  // Complete parsed response
await bot.process(input, {
  onToken: (botName, event) => {
    if (event.type === 'text_delta') {
      process.stdout.write(event.content);
    }
  }
});
// Don't await or use return value if you only care about streaming
const result = await bot.process(input);
// No onToken = no streaming, just wait for final result
console.log('Response:', result);
onToken(botName, event) {
  if (event.type === 'tool_execution_start') {
    console.log(`Starting ${event.toolName}`);
  }
}

Inherited from​

ProcessOptions.onToken

signal?​

optional signal?: AbortSignal

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

AbortSignal to cancel the request

Inherited from​

ProcessOptions.signal

stopWhen?​

optional stopWhen?: StopCondition

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

Override stopWhen for this call only. Takes precedence over construction-time stopWhen.

Inherited from​

ProcessOptions.stopWhen

temperature?​

optional temperature?: number

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

Override temperature for this call only (0–2). Takes precedence over construction-time temperature.

Inherited from​

ProcessOptions.temperature

toolCallId​

toolCallId: string

Defined in: packages/core/src/utils/tools.ts:62

Unique ID of this tool call

Overrides​

ProcessOptions.toolCallId

verbose?​

optional verbose?: boolean

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

Enable verbose logging for debugging

Inherited from​

ProcessOptions.verbose