API reference for icepick.tool.
icepick.tool
method creates a new tool that can be used by agents in Icepick.
run()
, runAndWait()
, runNoWait()
schedule()
, delay()
, cron()
Parameter | Type | Required | Description |
---|---|---|---|
name | string | Yes | A unique identifier for the tool. Used for tool registration and selection by agents. |
description | string | Yes | A human-readable description of what the tool does. Used by language models to decide when to use the tool. |
inputSchema | ZodType | Yes | Zod schema that defines and validates the input structure for the tool. |
outputSchema | ZodType | Yes | Zod schema that defines and validates the output structure returned by the tool. |
fn | (input: z.infer<InputSchema>, ctx?: Context) => Promise<z.infer<OutputSchema>> | Yes | The main tool function that processes input and returns output. Receives validated input and optional Context. |
executionTimeout | string | No | Execution timeout duration for the tool after it starts running. Go duration format (e.g., “1s”, “5m”, “1h”). Default: ”60s” |
scheduleTimeout | string | No | Schedule timeout for the tool (max duration to allow the tool to wait in the queue). Go duration format. Default: “5m” |
retries | number | No | Number of retries for the tool. Default: 0 |
concurrency | Concurrency | Concurrency[] | No | Concurrency configuration for the tool. Controls how many concurrent executions are allowed. |
defaultPriority | Priority | No | The priority for the tool. Values: Priority.LOW (1), Priority.MEDIUM (2), Priority.HIGH (3) |
onCrons | string[] | No | Cron config for the tool. |
onEvents | string[] | No | Event config for the tool. |
Property | Type | Required | Description |
---|---|---|---|
expression | string | Yes | The CEL expression to use for concurrency (e.g., “input.key”) |
maxRuns | number | No | The maximum number of concurrent workflow runs. Default: 1 |
limitStrategy | ConcurrencyLimitStrategy | No | The strategy to use when the concurrency limit is reached. Default: CANCEL_IN_PROGRESS |
icepick.tool
method returns a ToolDeclaration<InputSchema, OutputSchema> & { name: Name }
object with the following properties and methods:
Property | Type | Description |
---|---|---|
inputSchema | InputSchema | The Zod schema used for input validation |
outputSchema | OutputSchema | The Zod schema used for output validation |
description | string | The description of the tool |
name | string | The unique name identifier for the tool |
client | IHatchetClient | undefined | The Hatchet client instance used to execute the workflow |
definition | WorkflowDefinition | The internal workflow definition |
run(input, options?)
input
: z.infer<InputSchema>
- The input data for the tooloptions?
: RunOpts
- Optional configuration for this tool runPromise<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?)
run()
. Triggers a tool run and waits for the result.
Parameters:
input
: z.infer<InputSchema>
- The input data for the tooloptions?
: RunOpts
- Optional configuration for this tool runPromise<z.infer<OutputSchema>>
- A promise that resolves with the tool result
runNoWait(input, options?)
input
: z.infer<InputSchema>
- The input data for the tooloptions?
: RunOpts
- Optional configuration for this tool runPromise<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?)
enqueueAt
: Date
- The date when the tool should be triggeredinput
: z.infer<InputSchema>
- The input data for the tooloptions?
: RunOpts
- Optional configuration for this tool runPromise<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?)
duration
: number
- The delay in seconds before the tool should runinput
: z.infer<InputSchema>
- The input data for the tooloptions?
: RunOpts
- Optional configuration for this tool runPromise<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?)
name
: string
- The name of the cron scheduleexpression
: string
- The cron expression defining the scheduleinput
: z.infer<InputSchema>
- The input data for the tooloptions?
: RunOpts
- Optional configuration for this tool runPromise<CronWorkflows>
- A promise that resolves with the cron workflow details
Throws: Error if the tool is not bound to a Hatchet client
Property | Type | Required | Description |
---|---|---|---|
additionalMetadata | Record<string, string> | No | Additional metadata to attach to the workflow run |
priority | Priority | No | The priority for the workflow run. Values: Priority.LOW (1), Priority.MEDIUM (2), Priority.HIGH (3) |
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.
Property | Type | Description |
---|---|---|
input | T | The original input data for the tool |
workflowRunId() | () => string | Gets the ID of the current workflow run |
workflowName() | () => string | Gets the name of the current workflow |
taskName() | () => string | Gets the name of the current running task |
taskRunId() | () => string | Gets the ID of the current task run |
workflowId() | () => string | undefined | Gets the workflow ID |
workflowVersionId() | () => string | undefined | Gets the workflow version ID |
cancelled | boolean | Gets cancellation status |
controller | AbortController | The abort controller for the current task |
logger | Logger | Structured logging methods (info, debug, warn, error) |
Method | Parameters | Returns | Description |
---|---|---|---|
cancel() | None | Promise<void> | Cancels the current task |
refreshTimeout() | incrementBy: Duration | Promise<void> | Refreshes the timeout for the current task |
retryCount() | None | number | Gets the number of times the current task has been retried |
Method | Parameters | Returns | Description |
---|---|---|---|
putStream() | data: string | Uint8Array | Promise<void> | Streams data from the current task run |
additionalMetadata() | None | Record<string, string> | Retrieves additional metadata |
errors() | None | Record<string, string> | Returns errors from any task runs in the workflow |
triggers() | None | TriggerData | Gets the dag conditional triggers for the current workflow run |
filterPayload() | None | Record<string, any> | Gets the payload from the filter that matched when triggering the event |
triggeredByEvent() | None | boolean | Determines if the workflow was triggered by an event |
priority() | None | Priority | undefined | Gets the priority of the workflow |
icepick.agent
- Create agents that can use toolsicepick.toolbox
- Create collections of tools for agents to use