#Tool Call Engine

Tarko's Tool Call Engine determines how the Agent processes and executes tool calls. Different engines provide compatibility with various LLM providers and use cases.

#Overview

The Tool Call Engine handles:

• Function Call Parsing: How tool calls are extracted from LLM responses
• Provider Compatibility: Works with models that have different tool calling capabilities
• Execution Strategy: How tools are invoked and results processed
• Error Handling: Managing failed tool calls and retries

#Available Engine Types

Based on the actual ToolCallEngineType from the source code:

#1. Native Engine

Best for: Models with native function calling support (GPT-4, Claude 3.5, etc.)

import { Agent } from '@tarko/agent';

const agent = new Agent({
  toolCallEngine: 'native',
  model: {
    provider: 'openai',
    id: 'gpt-4o',
    apiKey: process.env.OPENAI_API_KEY,
  },
  tools: [weatherTool],
});

How it works:

• Uses the model's built-in function calling capabilities
• Sends tools as function definitions in the API request
• Parses structured function call responses
• Most reliable and efficient for supported models

#2. Prompt Engineering Engine

Best for: Models without native function calling or custom parsing needs

const agent = new Agent({
  toolCallEngine: 'prompt_engineering',
  model: {
    provider: 'volcengine', 
    id: 'doubao-seed-1-6-vision-250815',
    apiKey: process.env.ARK_API_KEY,
  },
  tools: [weatherTool],
});

How it works:

• Embeds tool descriptions in the system prompt
• Instructs the model to output tool calls in a specific format
• Parses tool calls from the text response using regex/patterns
• Provides fallback compatibility for any text-based model

#3. Structured Outputs Engine

Best for: Models that support structured output but not function calling

const agent = new Agent({
  toolCallEngine: 'structured_outputs',
  model: {
    provider: 'anthropic',
    id: 'claude-3-5-sonnet-20241022', 
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
  tools: [weatherTool],
});

How it works:

• Uses structured output schemas to enforce tool call format
• More reliable than prompt engineering for parsing
• Reduces parsing errors and improves consistency
• Works with models that support JSON schema constraints

#Engine Selection Guide

#Automatic Selection

Tarko can automatically select the best engine for your model:

// Tarko will choose the optimal engine based on the model provider
const agent = new Agent({
  // toolCallEngine not specified - auto-selected
  model: {
    provider: 'openai',
    id: 'gpt-4o',
    apiKey: process.env.OPENAI_API_KEY,
  },
  tools: [weatherTool],
});

#Manual Selection

Choose explicitly based on your needs:

// Force prompt engineering for custom control
const agent = new Agent({
  toolCallEngine: 'prompt_engineering',
  model: {
    provider: 'openai', // Even for OpenAI, use prompt engineering
    id: 'gpt-4o',
    apiKey: process.env.OPENAI_API_KEY,
  },
  tools: [weatherTool],
});

#Engine Comparison

#Real Examples from Source Code

#Basic Tool Call Engine Usage

From multimodal/tarko/agent/examples/tool-calls/basic.ts:

import { Agent, Tool, z, LogLevel } from '@tarko/agent';

const agent = new Agent({
  model: {
    provider: 'volcengine',
    id: 'doubao-seed-1-6-vision-250815',
    apiKey: process.env.ARK_API_KEY,
  },
  tools: [locationTool, weatherTool],
  logLevel: LogLevel.DEBUG,
  // toolCallEngine will be auto-selected based on model capabilities
});

#Streaming with Tool Call Engine

From multimodal/tarko/agent/examples/streaming/tool-calls.ts:

const agent = new Agent({
  model: {
    provider: 'volcengine',
    id: 'doubao-seed-1-6-vision-250815',
    apiKey: process.env.ARK_API_KEY,
  },
  tools: [locationTool, weatherTool],
  toolCallEngine: 'native',
  enableStreamingToolCallEvents: true,
});

#Debugging Tool Call Engines

#Enable Debug Logging

import { LogLevel } from '@tarko/agent';

const agent = new Agent({
  toolCallEngine: 'prompt_engineering',
  logLevel: LogLevel.DEBUG, // See detailed tool call parsing
  tools: [weatherTool],
});

#Monitor Tool Call Events

const response = await agent.run({
  input: "What's the weather?",
  stream: true,
});

for await (const event of response) {
  if (event.type === 'tool_call') {
    console.log('Tool called:', event.toolCall.function.name);
  }
  if (event.type === 'tool_result') {
    console.log('Tool result:', event.result);
  }
}

#Troubleshooting

#Common Issues

Tool calls not being detected:

• Check if the model supports the selected engine type
• Try switching to prompt_engineering for broader compatibility
• Verify tool descriptions are clear and specific

Parsing errors with prompt engineering:

• The model may not be following the expected format
• Try structured_outputs if the model supports schemas
• Simplify tool parameter schemas

Performance issues:

• native engine is fastest for supported models
• prompt_engineering adds parsing overhead
• Consider caching for expensive tool operations

#Engine Selection Decision Tree

Does your model support native function calling?
├─ Yes → Use 'native' (recommended)
└─ No
   ├─ Does it support structured outputs?
   │  ├─ Yes → Use 'structured_outputs'
   │  └─ No → Use 'prompt_engineering'
   └─ Need custom parsing logic?
      └─ Consider implementing custom engine

#Next Steps

• Tools - Learn how to create tools
• Configuration - Configure tool call engines
• Event Stream - Monitor tool call events