API reference for icepick.toolbox.
icepick.toolbox
method creates a new toolbox that contains a collection of tools for agents to use with AI-powered selection.
pick()
, pickAndRun()
assertExhaustive()
, getTools()
Parameter | Type | Required | Description |
---|---|---|---|
tools | ToolDeclaration[] | Yes | Array of tool declarations to register on the toolbox. These tools can be selected by AI. |
tools
parameter accepts an array of ToolDeclaration
objects created with icepick.tool()
.
Property | Type | Description |
---|---|---|
inputSchema | ZodType | The Zod schema used for input validation |
outputSchema | ZodType | The Zod schema used for output validation |
description | string | The description of the tool |
name | string | The unique name identifier for the tool |
icepick.toolbox
method returns a Toolbox<T>
object with the following properties and methods:
Property | Type | Description |
---|---|---|
toolSetForAI | ToolSet | AI-ready toolset used internally by language models for tool selection |
register | TaskWorkflowDeclaration[] | All user-supplied tool declarations plus internal workflows for Hatchet registration |
pick(options)
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 selectionPromise<Array<{ name: string, input: any }>>
- Array containing chosen tool names with generated input arguments
pickAndRun(options)
pick()
and then immediately executes the chosen tool(s).
Type Overloads:
maxTools
is omitted or 1
: Returns Promise<ToolResultMap<T>>
maxTools
> 1: Returns Promise<ToolResultMap<T>[]>
options
: PickInput
- Configuration for tool selection and executionPromise<ToolResultMap<T> | ToolResultMap<T>[]>
- Single tool result or array of results depending on maxTools
assertExhaustive(result)
default
case to ensure all tool results are handled.
Parameters:
result
: never
- The result to assert is exhaustivenever
- This method always throws
Throws: Error if the result is not exhaustive, indicating an unhandled tool result
getTools()
T
- The array of tool declarations provided when creating the toolbox
Property | Type | Required | Description |
---|---|---|---|
prompt | string | Yes | Natural-language description of what the caller wants to achieve |
maxTools | number | No | Maximum number of tools to select and execute. Default: 1 |
ToolResultMap<T>
is a discriminated union type that provides type-safe access to tool results:
Property | Type | Description |
---|---|---|
name | string | The name of the executed tool |
output | any | The output from the tool execution |
args | any | The input arguments that were passed to the tool |
Property | Type | Description |
---|---|---|
[toolName] | ToolDefinition | Tool definition object for each tool in the toolbox |
[toolName].parameters | any | The schema of the input that the tool expects |
[toolName].description | string | undefined | Optional description of what the tool does |
icepick.tool
- Create individual tools to add to toolboxesicepick.agent
- Create agents that can use toolboxes