Custom tools

Tools are the functions agents call during a conversation. This tutorial builds two tools: a standard async function that looks up an order from a REST API and returns JSON, and a streaming generator variant that yields progress updates while processing a batch operation.

Prerequisites

Completed Your first app — you have a working project with src/exulu.ts.
Read ExuluTool — introduction and ExuluTool — configuration.

What you will build

order_lookup — a standard tool with a Zod schema, two admin config params, needsApproval: false, and a {result} return.
batch_report_generator — a streaming tool that yields results incrementally as it processes items.

Create the tools file

Create src/tools/index.ts:

src/tools/index.ts

import { ExuluTool } from "@exulu/backend";
import { z } from "zod";

export const tools = [
  orderLookupTool,
  batchReportTool,
];

export default tools;

You will fill in orderLookupTool and batchReportTool in the following steps.

Build the order lookup tool

The order lookup tool fetches order details from an internal API. Because it is read-only and low-risk, needsApproval is false — the agent calls it without interrupting the user:

src/tools/order-lookup.ts

import { ExuluTool } from "@exulu/backend";
import { z } from "zod";

export const orderLookupTool = new ExuluTool({
  id: "order_lookup",
  name: "Order lookup",
  description: "Fetches order details from the order management system by order ID. Use this tool when the user asks about a specific order, its status, or its line items.",
  type: "function",
  category: "orders",

  inputSchema: z.object({
    orderId: z
      .string()
      .describe("The order ID to look up, e.g. ORD-2026-00123."),
    includeLineItems: z
      .boolean()
      .optional()
      .describe("Whether to include individual line items in the response. Defaults to false."),
  }),

  config: [
    {
      name: "orders_api_url",
      description: "Base URL of the order management API.",
      type: "string",
      default: "https://orders.internal/api/v2",
    },
    {
      name: "orders_api_key",
      description: "API key for the order management system (stored encrypted).",
      type: "variable",
    },
  ],

  needsApproval: false,

  execute: async ({ orderId, includeLineItems = false, toolVariablesConfig }) => {
    const apiUrl = toolVariablesConfig.orders_api_url ?? "https://orders.internal/api/v2";
    const apiKey = toolVariablesConfig.orders_api_key;

    const url = new URL(`${apiUrl}/orders/${orderId}`);
    if (includeLineItems) url.searchParams.set("expand", "line_items");

    const response = await fetch(url.toString(), {
      headers: { Authorization: `Bearer ${apiKey}` },
    });

    if (response.status === 404) {
      return { result: JSON.stringify({ error: "Order not found", orderId }) };
    }
    if (!response.ok) {
      return { result: JSON.stringify({ error: `API error ${response.status}`, orderId }) };
    }

    const order = await response.json();
    return { result: JSON.stringify(order) };
  },
});

A few points about this tool:

config params — orders_api_url (type "string") and orders_api_key (type "variable") are set by an administrator in the agent workbench, not in code. Variable-type params are stored encrypted and looked up at call time. The agent never sees them.
Reading those params — they arrive as toolVariablesConfig on the first argument, keyed by param name, already decrypted. They are not on the second (options) argument, which carries only AI-SDK context. See Reading config values at runtime. If an administrator has not configured the tool, toolVariablesConfig is {} — the ?? fallback above is deliberate for a URL, but never fall back to a default credential or tenant.
needsApproval: false — read-only, reversible operations should not block the user. Set true (the default) for any action that modifies data or has side effects.
Return shape — { result: string } is the standard return for tools that produce a text or JSON response. Always JSON.stringify objects before returning — agents parse JSON automatically.

Always set needsApproval explicitly on a read-only tool. It defaults to true, so omitting it makes a plain read prompt the user — and the cost is worse than one extra click, because models fan reads out in parallel. A single turn that reads twenty records issues twenty tool calls in one step, each with its own approval prompt, and the run cannot continue until every one has been answered individually. “Allow for this chat” does not rescue it: approval is evaluated for all twenty calls before the first prompt reaches the browser.Write the flag on every tool, both ways. needsApproval: true on a tool that writes documents the intent; needsApproval: false on a tool that reads documents that the default was considered rather than inherited.

Build a streaming tool

Return an AsyncGenerator from execute for long-running operations that should stream progress to the agent. Each yielded value is the same { result } shape:

src/tools/batch-report.ts

import { ExuluTool } from "@exulu/backend";
import { z } from "zod";

export const batchReportTool = new ExuluTool({
  id: "batch_report_generator",
  name: "Batch report generator",
  description: "Generates a usage report for a list of account IDs. Each account is processed in sequence and results are streamed back as they complete.",
  type: "function",
  category: "reports",

  inputSchema: z.object({
    accountIds: z
      .array(z.string())
      .min(1)
      .max(50)
      .describe("Account IDs to include in the report, e.g. [\"ACC-001\", \"ACC-002\"]."),
    period: z
      .enum(["last_7_days", "last_30_days", "last_90_days"])
      .describe("Reporting period."),
  }),

  config: [
    {
      name: "reporting_api_url",
      description: "Base URL of the reporting service.",
      type: "string",
      default: "https://reporting.internal/api",
    },
  ],

  needsApproval: true, // prompts the user before running — it hits external services

  execute: async function* ({ accountIds, period, toolVariablesConfig }) {
    const apiUrl = toolVariablesConfig.reporting_api_url ?? "https://reporting.internal/api";

    for (const accountId of accountIds) {
      try {
        const response = await fetch(`${apiUrl}/accounts/${accountId}/report?period=${period}`);
        const data = await response.json();

        yield {
          result: JSON.stringify({
            accountId,
            status: "ok",
            report: data,
          }),
        };
      } catch (error) {
        yield {
          result: JSON.stringify({
            accountId,
            status: "error",
            message: error instanceof Error ? error.message : "Unknown error",
          }),
        };
      }
    }
  },
});

The async function* syntax marks execute as an async generator. IMP’s framework handles both the regular Promise and AsyncGenerator return types — the agent sees a stream of result tokens as each yield resolves.

src/exulu.ts

import { ExuluApp } from "@exulu/backend";
import { contexts } from "./contexts/index";
import { orderLookupTool } from "./tools/order-lookup";
import { batchReportTool } from "./tools/batch-report";

export const app = new ExuluApp();

export const ready = app.create({
  config: {
    fileUploads: {
      s3region:   process.env.COMPANION_S3_REGION!,
      s3key:      process.env.COMPANION_S3_KEY!,
      s3secret:   process.env.COMPANION_S3_SECRET!,
      s3Bucket:   process.env.COMPANION_S3_BUCKET!,
      s3endpoint: process.env.COMPANION_S3_ENDPOINT,
    },
    workers: { enabled: true },
    MCP:     { enabled: false },
  },
  contexts,
  tools: [orderLookupTool, batchReportTool],
});

After starting the server, both tools appear in the agent workbench under Build → Agents → [agent] → Tools & skills. An administrator enables them per agent and fills in the config param values.

Verify tool behavior

Start the server and open the agent workbench. Enable order_lookup on an agent, set the config params, and send a test message that prompts the agent to look up an order. Because needsApproval: false, the agent calls the tool immediately without a confirmation prompt.Enable batch_report_generator on the same agent. When prompted to generate a report, the agent surfaces a Confirm dialog (because needsApproval: true) before calling the tool. After approval, streaming results appear in the conversation.

What you built

order_lookup — a standard async tool with a Zod schema, two admin config params (one a "variable" for secrets), and needsApproval: false.
batch_report_generator — a streaming AsyncGenerator tool that yields progress for each processed account.

Next steps

OAuth tools

Wrap a tool in an OAuth 2.0 flow so agents can act on behalf of the signed-in user.

ExuluTool — configuration

Full reference for every constructor option including the ExuluOauthConfig shape.

Tools and skills

Enable and configure tools in the agent workbench UI.

Start

Tutorials

Recipes

Core classes

Reference

Prerequisites

What you will build

What you built

Next steps

OAuth tools

ExuluTool — configuration

Tools and skills

​Prerequisites

​What you will build

​What you built

​Next steps

OAuth tools

ExuluTool — configuration

Tools and skills

Prerequisites

What you will build

What you built

Next steps