The icepick.tool method creates a new tool that can be used by agents in Icepick.

Quick Reference

Usage Example

import { z } from "zod";
import { icepick } from "@hatchet-dev/icepick";

export const myTool = icepick.tool({
  name: "my-tool",
  description: "Description of what this tool does",
  inputSchema: z.object({
    // TODO: Define your input schema here
    // Example: input: z.string().describe("The input parameter")
  }),
  outputSchema: z.object({
    // TODO: Define your output schema here
    // Example: result: z.string().describe("The tool result")
  }),
  fn: async (input) => {
    try {
      // TODO: Implement your tool logic here
      // Example API call:
      // const response = await fetch(`https://api.example.com/data?param=${input.param}`);
      // const data = await response.json();

      return {
        // TODO: Return your tool output here
        // Example: result: data.message
      };
    } catch (error) {
      return {
        // TODO: Handle errors appropriately for your tool
        // Example: result: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`
      };
    }
  },
});

Parameters

ParameterTypeRequiredDescription
namestringYesA unique identifier for the tool. Used for tool registration and selection by agents.
descriptionstringYesA human-readable description of what the tool does. Used by language models to decide when to use the tool.
inputSchemaZodTypeYesZod schema that defines and validates the input structure for the tool.
outputSchemaZodTypeYesZod schema that defines and validates the output structure returned by the tool.
fn(input: z.infer<InputSchema>, ctx?: Context) => Promise<z.infer<OutputSchema>>YesThe main tool function that processes input and returns output. Receives validated input and optional Context.
executionTimeoutstringNoExecution timeout duration for the tool after it starts running. Go duration format (e.g., “1s”, “5m”, “1h”). Default: ”60s”
scheduleTimeoutstringNoSchedule timeout for the tool (max duration to allow the tool to wait in the queue). Go duration format. Default: “5m”
retriesnumberNoNumber of retries for the tool. Default: 0
concurrencyConcurrency | Concurrency[]NoConcurrency configuration for the tool. Controls how many concurrent executions are allowed.
defaultPriorityPriorityNoThe priority for the tool. Values: Priority.LOW (1), Priority.MEDIUM (2), Priority.HIGH (3)
onCronsstring[]NoCron config for the tool.
onEventsstring[]NoEvent config for the tool.

Concurrency Type

PropertyTypeRequiredDescription
expressionstringYesThe CEL expression to use for concurrency (e.g., “input.key”)
maxRunsnumberNoThe maximum number of concurrent workflow runs. Default: 1
limitStrategyConcurrencyLimitStrategyNoThe strategy to use when the concurrency limit is reached. Default: CANCEL_IN_PROGRESS

Returns

The icepick.tool method returns a ToolDeclaration<InputSchema, OutputSchema> & { name: Name } object with the following properties and methods:

Properties

PropertyTypeDescription
inputSchemaInputSchemaThe Zod schema used for input validation
outputSchemaOutputSchemaThe Zod schema used for output validation
descriptionstringThe description of the tool
namestringThe unique name identifier for the tool
clientIHatchetClient | undefinedThe Hatchet client instance used to execute the workflow
definitionWorkflowDefinitionThe internal workflow definition

Methods

run(input, options?)

Executes the tool with the given input and waits for completion. Parameters:
  • input: z.infer<InputSchema> - The input data for the tool
  • options?: RunOpts - Optional configuration for this tool run
Returns: Promise<z.infer<OutputSchema>> - A promise that resolves with the tool result Throws: Error if the tool is not bound to a Hatchet client

runAndWait(input, options?)

Alias for run(). Triggers a tool run and waits for the result. Parameters:
  • input: z.infer<InputSchema> - The input data for the tool
  • options?: RunOpts - Optional configuration for this tool run
Returns: Promise<z.infer<OutputSchema>> - A promise that resolves with the tool result

runNoWait(input, options?)

Triggers the tool execution without waiting for completion. Parameters:
  • input: z.infer<InputSchema> - The input data for the tool
  • options?: RunOpts - Optional configuration for this tool run
Returns: Promise<WorkflowRunRef<z.infer<OutputSchema>>> - A WorkflowRunRef containing the run ID and methods to get results and interact with the run Throws: Error if the tool is not bound to a Hatchet client

schedule(enqueueAt, input, options?)

Schedules the tool to run at a specific date and time in the future. Parameters:
  • enqueueAt: Date - The date when the tool should be triggered
  • input: z.infer<InputSchema> - The input data for the tool
  • options?: RunOpts - Optional configuration for this tool run
Returns: Promise<ScheduledWorkflows> - A promise that resolves with the scheduled workflow details Throws: Error if the tool is not bound to a Hatchet client

delay(duration, input, options?)

Schedules the tool to run after a specified delay. Parameters:
  • duration: number - The delay in seconds before the tool should run
  • input: z.infer<InputSchema> - The input data for the tool
  • options?: RunOpts - Optional configuration for this tool run
Returns: Promise<ScheduledWorkflows> - A promise that resolves with the scheduled workflow details Throws: Error if the tool is not bound to a Hatchet client

cron(name, expression, input, options?)

Creates a cron schedule for recurring tool execution. Parameters:
  • name: string - The name of the cron schedule
  • expression: string - The cron expression defining the schedule
  • input: z.infer<InputSchema> - The input data for the tool
  • options?: RunOpts - Optional configuration for this tool run
Returns: Promise<CronWorkflows> - A promise that resolves with the cron workflow details Throws: Error if the tool is not bound to a Hatchet client

RunOpts Type

PropertyTypeRequiredDescription
additionalMetadataRecord<string, string>NoAdditional metadata to attach to the workflow run
priorityPriorityNoThe priority for the workflow run. Values: Priority.LOW (1), Priority.MEDIUM (2), Priority.HIGH (3)

Context

The optional ctx parameter in the tool function provides access to the Hatchet workflow execution context. When present, it offers comprehensive capabilities for workflow management, logging, and execution control.

Core Properties

PropertyTypeDescription
inputTThe original input data for the tool
workflowRunId()() => stringGets the ID of the current workflow run
workflowName()() => stringGets the name of the current workflow
taskName()() => stringGets the name of the current running task
taskRunId()() => stringGets the ID of the current task run
workflowId()() => string | undefinedGets the workflow ID
workflowVersionId()() => string | undefinedGets the workflow version ID
cancelledbooleanGets cancellation status
controllerAbortControllerThe abort controller for the current task
loggerLoggerStructured logging methods (info, debug, warn, error)

Execution Control Methods

MethodParametersReturnsDescription
cancel()NonePromise<void>Cancels the current task
refreshTimeout()incrementBy: DurationPromise<void>Refreshes the timeout for the current task
retryCount()NonenumberGets the number of times the current task has been retried

Logging & Data Methods

MethodParametersReturnsDescription
putStream()data: string | Uint8ArrayPromise<void>Streams data from the current task run
additionalMetadata()NoneRecord<string, string>Retrieves additional metadata
errors()NoneRecord<string, string>Returns errors from any task runs in the workflow
triggers()NoneTriggerDataGets the dag conditional triggers for the current workflow run
filterPayload()NoneRecord<string, any>Gets the payload from the filter that matched when triggering the event
triggeredByEvent()NonebooleanDetermines if the workflow was triggered by an event
priority()NonePriority | undefinedGets the priority of the workflow