Skip to main content
The icepick.toolbox method creates a new toolbox that contains a collection of tools for agents to use with AI-powered selection.

​
Quick Reference

​
Usage Example

import { icepick } from "@hatchet-dev/icepick";
import z from "zod";
// Import your tools
import { searchTool, emailTool } from "@/tools";

export const myToolbox = icepick.toolbox({
  tools: [
    searchTool,
    emailTool,
    // Add more tools here
  ],
});

export const myAgent = icepick.agent({
  name: "my-agent",
  executionTimeout: "15m",
  inputSchema: z.object({
    message: z.string().describe("The user's request message"),
  }),
  outputSchema: z.object({
    message: z.string().describe("The agent's response message"),
  }),
  description: "An agent that uses tools from a toolbox",
  fn: async (input, ctx) => {
    const result = await myToolbox.pickAndRun({
      prompt: input.message,
    });

    switch (result.name) {
      case "searchTool":
        return {
          message: `Search results: ${result.output.results.join(", ")}`,
        };
      case "emailTool":
        return {
          message: `Email sent: ${result.output.status}`,
        };
      default:
        return myToolbox.assertExhaustive(result);
    }
  },
});

​
Parameters

ParameterTypeRequiredDescription
toolsToolDeclaration[]YesArray of tool declarations to register on the toolbox. These tools can be selected by AI.

​
ToolDeclaration Array

The tools parameter accepts an array of ToolDeclaration objects created with icepick.tool().
PropertyTypeDescription
inputSchemaZodTypeThe Zod schema used for input validation
outputSchemaZodTypeThe Zod schema used for output validation
descriptionstringThe description of the tool
namestringThe unique name identifier for the tool

​
Returns

The icepick.toolbox method returns a Toolbox<T> object with the following properties and methods:

​
Properties

PropertyTypeDescription
toolSetForAIToolSetAI-ready toolset used internally by language models for tool selection
registerTaskWorkflowDeclaration[]All user-supplied tool declarations plus internal workflows for Hatchet registration

​
Methods

​
pick(options)

Uses the language model to choose up to maxTools tools from this toolbox that best satisfy the provided prompt. Only tool selection is performed—no execution happens. Parameters:
  • options: PickInput - Configuration for tool selection
Returns: Promise<Array<{ name: string, input: any }>> - Array containing chosen tool names with generated input arguments

​
pickAndRun(options)

Convenience method that first runs pick() and then immediately executes the chosen tool(s). Type Overloads:
  • When maxTools is omitted or 1: Returns Promise<ToolResultMap<T>>
  • When maxTools > 1: Returns Promise<ToolResultMap<T>[]>
Parameters:
  • options: PickInput - Configuration for tool selection and execution
Returns: Promise<ToolResultMap<T> | ToolResultMap<T>[]> - Single tool result or array of results depending on maxTools

​
assertExhaustive(result)

Helper method to assert that toolbox results are exhaustive for handling in switch statements. Use this in the default case to ensure all tool results are handled. Parameters:
  • result: never - The result to assert is exhaustive
Returns: never - This method always throws Throws: Error if the result is not exhaustive, indicating an unhandled tool result

​
getTools()

Gets the original tool declarations used internally by the pick-tool workflow. Returns: T - The array of tool declarations provided when creating the toolbox

​
PickInput Type

PropertyTypeRequiredDescription
promptstringYesNatural-language description of what the caller wants to achieve
maxToolsnumberNoMaximum number of tools to select and execute. Default: 1

​
ToolResultMap Type

The ToolResultMap<T> is a discriminated union type that provides type-safe access to tool results:
PropertyTypeDescription
namestringThe name of the executed tool
outputanyThe output from the tool execution
argsanyThe input arguments that were passed to the tool
This allows you to use switch statements with full TypeScript type checking: 
const result = await toolbox.pickAndRun({ prompt: "Do something" });

switch (result.name) {
  case "myTool":
    // result.output is properly typed for myTool's output
    console.log(result.output);
    break;
  case "anotherTool":
    // result.output is properly typed for anotherTool's output
    console.log(result.output);
    break;
  default:
    return toolbox.assertExhaustive(result);
}

​
ToolSet Type

The AI-ready toolset used internally by language models for tool selection:
PropertyTypeDescription
[toolName]ToolDefinitionTool definition object for each tool in the toolbox
[toolName].parametersanyThe schema of the input that the tool expects
[toolName].descriptionstring | undefinedOptional description of what the tool does
⌘I