Tool Calling

Extend AI capabilities with built-in and custom tools through an agentic loop.

Overview

Tool calling allows the AI to:

• Execute functions and workflows
• Search knowledge bases (RAG)
• Browse web pages
• Execute SQL queries
• Interact with browser sessions
• Send emails and notifications
• Access external APIs

Agentic Loop

The chat system uses an agentic loop for tool calling:

User Message
     │
     ▼
┌─────────────────────────────┐
│  Agentic Loop               │
│  (max 8 iterations)         │
│                             │
│  For each iteration:        │
│  1. Send "thinking" event   │
│  2. Call LLM with tools     │
│  3. Parse tool calls        │
│  4. If no tools → respond   │
│  5. Execute each tool       │
│  6. Add results to context  │
│  7. Next iteration          │
└─────────────────────────────┘
     │
     ▼
Final Response

Key Features

• Maximum 8 iterations: Prevents runaway loops
• Loop detection: Stops repeated identical tool calls
• Parallel execution: Multiple tools can run concurrently
• Result truncation: Large results are trimmed to save context
• Error handling: Failed tools report errors, loop continues

Built-in Tools

search_knowledge

Search the knowledge base for relevant information.

{
  "name": "search_knowledge",
  "arguments": {
    "query": "React hooks tutorial"
  }
}

browse_url

Fetch and read content from a URL.

{
  "name": "browse_url",
  "arguments": {
    "url": "https://example.com/article"
  }
}

browser_action

Execute actions in a browser session.

{
  "name": "browser_action",
  "arguments": {
    "sessionId": "session-123",
    "action": "click",
    "selector": "#submit-button"
  }
}

analyze_page

Analyze the current browser page content.

{
  "name": "analyze_page",
  "arguments": {
    "sessionId": "session-123"
  }
}

execute_sql

Execute a SQL query against the database.

{
  "name": "execute_sql",
  "arguments": {
    "query": "SELECT * FROM users WHERE status = 'active'"
  }
}

execute_workflow

Run a workflow and return results.

{
  "name": "execute_workflow",
  "arguments": {
    "workflowId": "wf-123",
    "input": {"email": "[email protected]"}
  }
}

send_email

Send an email message.

{
  "name": "send_email",
  "arguments": {
    "to": "[email protected]",
    "subject": "Hello",
    "body": "Message content"
  }
}

get_schedule_info

Get information about scheduled tasks.

{
  "name": "get_schedule_info",
  "arguments": {
    "scheduleId": "sched-123"
  }
}

create_schedule

Create a new scheduled task.

{
  "name": "create_schedule",
  "arguments": {
    "name": "Daily Report",
    "cron": "0 9 * * *",
    "workflowId": "wf-123"
  }
}

Tool Message Format

Tool Call (from AI)

{
  "role": "assistant",
  "content": null,
  "toolCalls": [
    {
      "id": "tc_abc123",
      "name": "search_knowledge",
      "arguments": {"query": "React tutorials"}
    }
  ]
}

Tool Result (from system)

{
  "role": "tool",
  "toolCallId": "tc_abc123",
  "content": "{\"results\": [...]}"
}

Streaming Tool Events

During streaming, tool execution emits SSE events:

tool_call Event

Sent when a tool is being called:

event: message
data: {"type": "tool_call", "id": "tc_abc123", "name": "search_knowledge", "arguments": {"query": "React"}}

tool_result Event

Sent when tool execution completes:

event: message
data: {"type": "tool_result", "toolCallId": "tc_abc123", "name": "search_knowledge", "success": true, "result": [...], "resultPreview": "Found 5 results"}

For errors:

event: message
data: {"type": "tool_result", "toolCallId": "tc_abc123", "success": false, "error": "Search failed"}

Loop Detection

The system prevents infinite loops by:

1. Tracking recent calls: Last 10 tool calls are remembered
2. Argument comparison: Detects same tool with same arguments
3. Maximum repeats: Same call allowed maximum 2 times
4. Force exit: Loop terminates after 8 iterations regardless

Enabling Tools

Via API Request

{
  "content": "Search for React tutorials",
  "enableTools": true
}

Via Agent Settings

Configure in agent settings:

{
  "tools_enabled": true,
  "enabled_tools": ["search_knowledge", "browse_url", "execute_sql"]
}

Via Chat Interface

Toggle the "Tools" switch in the chat settings panel.

Custom Tools via MCP

Add custom tools using MCP (Model Context Protocol) servers:

{
  "type": "mcp",
  "config": {
    "server_id": "my-mcp-server",
    "tool_name": "custom_search"
  }
}

See MCP Servers for configuration details.

Tool Schema

Define tools with JSON Schema parameters:

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or coordinates"
      },
      "units": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      }
    },
    "required": ["location"]
  }
}

Result Handling

Truncation

Large results are automatically truncated:

• Results over 10,000 characters are truncated
• Base64 images are replaced with placeholders
• Preview text is generated for UI display

Screenshot Results

Browser tools that return screenshots:

• Full image stored in R2
• Placeholder added to context: [image displayed above]
• URL provided for display in UI

Best Practices

1. Clear Tool Descriptions

Write descriptive tool descriptions:

{
  "description": "Search the product catalog by name, category, or price range. Returns up to 10 matching products with name, price, and availability."
}

2. Validate Parameters

Define required fields and types:

{
  "parameters": {
    "properties": {
      "email": {
        "type": "string",
        "format": "email",
        "description": "Customer email address"
      }
    },
    "required": ["email"]
  }
}

3. Handle Errors Gracefully

Return clear error messages:

{
  "error": "Product not found",
  "code": "NOT_FOUND",
  "suggestion": "Try searching with a different query"
}

4. Limit Tool Count

Only enable needed tools:

• Reduces model confusion
• Faster response times
• Lower token costs
• Better focused responses

5. Monitor Tool Usage

Track tool metrics:

• Call frequency
• Success/failure rates
• Response times
• Token usage per tool

Example: Multi-Tool Interaction

User: "Find React tutorials and summarize the best one"

The AI will:

1. Iteration 1: Call search_knowledge

   {"name": "search_knowledge", "arguments": {"query": "React tutorials"}}

2. Result: Returns list of tutorials

3. Iteration 2: Call browse_url for top result

   {"name": "browse_url", "arguments": {"url": "https://example.com/react-guide"}}

4. Result: Returns page content

5. Final Response: AI synthesizes information and returns summary

API Reference

Get Available Tools

GET /api/agents/{id}/chat/tools

Response:

{
  "tools": [
    {
      "name": "search_knowledge",
      "description": "Search the knowledge base",
      "parameters": {...}
    },
    ...
  ]
}

See Tools API for complete endpoint documentation.