Advanced Tools

Enhance your tools with structured ToolResult outputs and enable multi-agent routing with createHandoffTool.

Structured Tool Output (ToolResult)

By default, tools can return strings or basic objects which are automatically serialized for the LLM. However, for more robust error handling and structured tool agent output, you can return a ToolResult.

A ToolResult allows you to explicitly mark a tool execution as successful or failed, separating the data payload from error messages. When a tool returns success: false, the agent run loop will present the error to the LLM, giving it an opportunity to self-correct and try again.

tool-result.ts

import { defineTool, ToolResult } from "@mehularora/stark-kit";
import z from "zod";

const dbQueryTool = defineTool({
  name: "queryDatabase",
  description: "Execute read-only SQL queries.",
  parameters: z.object({ sql: z.string() }),
  execute: async ({ sql }): Promise<ToolResult> => {
    try {
      const data = await executeSql(sql);
      // Return a structured success object with data
      return { success: true, data };
    } catch (err) {
      // The model receives this error structurally and can self-correct
      return {
        success: false,
        error: err instanceof Error ? err.message : String(err),
      };
    }
  },
});

Tip: Stark-Kit provides an isToolResult(value) type-guard to check if an arbitrary object conforms to the ToolResult interface.

Agent Handoffs

Use createHandoffTool(targetAgent) to give an agent the ability to transfer execution to another agent. When the agent calls the handoff tool, the run loop transparently switches to the target agent and continues from there.

handoff.ts

import { Agent, run, createHandoffTool, MistralProvider } from "@mehularora/stark-kit";

const provider = new MistralProvider();

// Specialized downstream agent
const billingAgent = new Agent({
  name: "BillingAgent",
  provider,
  instructions: "You handle billing questions.",
});

// The triage agent routes to the right specialist
const triageAgent = new Agent({
  name: "TriageAgent",
  provider,
  instructions: "Determine intent and hand off.",
  tools: [
    createHandoffTool(billingAgent), // ← Automatically generates a tool for handoff
  ],
});

Note: You can chain handoffs across many agents. After the loop completes, response.agent tells you which agent produced the final answer.