Agent Tools

What is Agent Mode?

By default, Kody operates as a simple chat proxy: it sends the user's message to your AI backend with a system prompt and streams back the response. Agent mode upgrades this to a tool-calling loop where the AI can autonomously decide to call tools, process their results, and continue generating a response.

When agent mode is enabled and your AI backend supports function calling, the flow becomes:

1. User sends a message
2. The AI generates a response, optionally requesting tool calls
3. If tool calls are requested, Kody executes them and feeds the results back to the AI
4. The AI continues generating, possibly calling more tools
5. Once the AI produces a final text response (no more tool calls), it is streamed to the user

A circuit breaker limits the maximum number of tool calls per message (configurable via tools.maxToolCalls, default 5) to prevent runaway loops.

Built-in Tools

Kody provides two built-in tools that are automatically available when their prerequisites are met:

Custom Tools

Define custom tools that call your own HTTP endpoints. The AI decides when to use them based on the tool description and the conversation context.

When the AI calls a custom tool, Kody sends a POST request to the endpoint with this body:

{
  "tool": "order_lookup",
  "arguments": {
    "order_id": "ORD-12345"
  }
}

Your endpoint should return a JSON response. The response body is passed back to the AI as the tool result.

Example: Order Lookup Tool

Here is a complete example of a custom tool that lets the AI look up order status:

{
  "tools": {
    "enabled": true,
    "maxToolCalls": 5,
    "builtinTools": {
      "knowledgeSearch": true
    },
    "customTools": [
      {
        "name": "order_lookup",
        "description": "Look up the status of a customer order by order ID. Use this when a customer asks about their order status, shipping, or delivery.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "The order ID (e.g. ORD-12345)"
            }
          },
          "required": ["order_id"]
        },
        "endpoint": {
          "url": "https://api.example.com/orders/lookup",
          "method": "POST",
          "headers": {
            "Authorization": "Bearer your-api-token"
          },
          "timeoutMs": 5000
        }
      }
    ]
  }
}

With this configuration, when a user asks "Where is my order ORD-12345?", the AI will call the order_lookup tool, receive the order data from your API, and respond with a natural language summary of the order status.

Widget UI

When the AI calls a tool, users see a compact status indicator in the chat (not a message bubble):

• In progress: A small spinner with descriptive text (e.g. "Searching knowledge base...", "Looking up order...")
• Completed: The spinner becomes a checkmark and the indicator fades slightly

Tool indicators are ephemeral — they are not stored in the conversation history and do not persist across page reloads. The final AI response (which incorporates tool results) is what gets saved.

Capability Detection

Kody automatically probes your AI backend to detect whether it supports tool calling and embeddings. Results are cached for 1 hour per backend. If your backend does not support tools, Kody falls back gracefully: