pickaxe.toolbox

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

​

Quick Reference

• Tool selection methods: pick(), pickAndRun()
• Utility methods: assertExhaustive(), getTools()

​

Usage Example

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

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

export const myAgent = pickaxe.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);
    }
  },
});

export default [myAgent, myToolbox];

​

Parameters

​

ToolDeclaration Array

The tools parameter accepts an array of ToolDeclaration objects created with pickaxe.tool().

​

Returns

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

​

Properties

​

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

​

ToolResultMap Type

The ToolResultMap<T> is a discriminated union type that provides type-safe access to tool results:

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:

​

Related

• pickaxe.tool - Create individual tools to add to toolboxes
• pickaxe.agent - Create agents that can use toolboxes
• Hatchet Documentation - Learn more about the underlying workflow engine