icepick.agent

The icepick.agent method creates a new instance of an agent in Icepick.

Quick Reference

Main execution methods: run(), runAndWait(), runNoWait()
Scheduling methods: schedule(), delay(), cron()

Usage Example

import { icepick } from "@hatchet-dev/icepick";
import z from "zod";
// TODO: Import your tools here
// Example: import { myTool } from "@/tools/my-tool";

const MyAgentInput = z.object({
  message: z.string(),
});

const MyAgentOutput = z.object({
  message: z.string(),
});

export const myToolbox = icepick.toolbox({
  // See icepick.toolbox documentation
  tools: [
    // TODO: Add your tools here
    // Example: myTool,
  ],
});

export const myAgent = icepick.agent({
  name: "my-agent",
  executionTimeout: "15m",
  inputSchema: MyAgentInput,
  outputSchema: MyAgentOutput,
  description: "Description of what this agent does",
  fn: async (input, ctx) => {
    const result = await myToolbox.pickAndRun({
      prompt: input.message,
    });

    switch (result.name) {
      // TODO: Handle your tool results here
      // Example:
      // case "myTool":
      //   return {
      //     message: `Result: ${result.output}`,
      //   };
      default:
        return myToolbox.assertExhaustive(result);
    }
  },
});

Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	A unique identifier for the agent. Used for workflow registration and execution.
`description`	`string`	Yes	A human-readable description of what the agent does and its purpose.
`inputSchema`	`ZodType`	Yes	Zod schema that defines and validates the input structure for the agent.
`outputSchema`	`ZodType`	Yes	Zod schema that defines and validates the output structure returned by the agent.
`fn`	`(input: z.infer<InputSchema>, ctx: DurableContext<z.infer<InputSchema>>) => Promise<z.infer<OutputSchema>>`	Yes	The main agent function that processes input and returns output. Receives validated input and DurableContext.
`executionTimeout`	`string`	No	Execution timeout duration for the agent after it starts running. Go duration format (e.g., “1s”, “5m”, “1h”). Default: ”60s”
`scheduleTimeout`	`string`	No	Schedule timeout for the agent (max duration to allow the agent to wait in the queue). Go duration format. Default: “5m”
`retries`	`number`	No	Number of retries for the agent. Default: 0
`concurrency`	`Concurrency` \| `Concurrency[]`	No	Concurrency configuration for the agent. Controls how many concurrent executions are allowed.
`defaultPriority`	`Priority`	No	The priority for the agent. Values: Priority.LOW (1), Priority.MEDIUM (2), Priority.HIGH (3)
`onCrons`	`string[]`	No	Cron config for the agent.
`onEvents`	`string[]`	No	Event config for the agent.

Concurrency Type

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

Returns

The icepick.agent method returns an AgentDeclaration<InputSchema, OutputSchema> object with the following properties and methods:

Properties

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 agent
`name`	`string`	The unique name identifier for the agent
`client`	`IHatchetClient \| undefined`	The Hatchet client instance used to execute the workflow
`definition`	`WorkflowDefinition`	The internal workflow definition

Methods

`run(input, options?)`

Executes the agent with the given input and waits for completion. Parameters:

input: z.infer<InputSchema> - The input data for the agent
options?: RunOpts - Optional configuration for this agent run

Returns: Promise<z.infer<OutputSchema>> - A promise that resolves with the agent result Throws: Error if the agent is not bound to a Hatchet client

`runAndWait(input, options?)`

Alias for run(). Triggers an agent run and waits for the result. Parameters:

input: z.infer<InputSchema> - The input data for the agent
options?: RunOpts - Optional configuration for this agent run

Returns: Promise<z.infer<OutputSchema>> - A promise that resolves with the agent result

`runNoWait(input, options?)`

Triggers the agent execution without waiting for completion. Parameters:

input: z.infer<InputSchema> - The input data for the agent
options?: RunOpts - Optional configuration for this agent 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 agent is not bound to a Hatchet client

`schedule(enqueueAt, input, options?)`

Schedules the agent to run at a specific date and time in the future. Parameters:

enqueueAt: Date - The date when the agent should be triggered
input: z.infer<InputSchema> - The input data for the agent
options?: RunOpts - Optional configuration for this agent run

Returns: Promise<ScheduledWorkflows> - A promise that resolves with the scheduled workflow details Throws: Error if the agent is not bound to a Hatchet client

`delay(duration, input, options?)`

Schedules the agent to run after a specified delay. Parameters:

duration: number - The delay in seconds before the agent should run
input: z.infer<InputSchema> - The input data for the agent
options?: RunOpts - Optional configuration for this agent run

Returns: Promise<ScheduledWorkflows> - A promise that resolves with the scheduled workflow details Throws: Error if the agent is not bound to a Hatchet client

`cron(name, expression, input, options?)`

Creates a cron schedule for recurring agent 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 agent
options?: RunOpts - Optional configuration for this agent run

Returns: Promise<CronWorkflows> - A promise that resolves with the cron workflow details Throws: Error if the agent is not bound to a Hatchet client

RunOpts Type

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)

DurableContext

The ctx parameter in the agent function provides a DurableContext object that extends the standard workflow context with durable execution capabilities. This context persists across worker restarts and transient failures, making it essential for long-running agent workflows.

Core Properties

Property	Type	Description
`input`	`T`	The original input data for the agent
`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)

Durable Execution Methods

Method	Parameters	Returns	Description
`sleepFor()`	`duration: Duration, readableDataKey?: string`	`Promise<Record<string, any>>`	Pauses execution for a specified duration that persists across restarts
`waitFor()`	`conditions: [Conditions](#conditions-type) \| [Conditions[]](#conditions-type)`	`Promise<Record<string, any>>`	Waits for specific conditions to be met, persisting across failures

Execution Control

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

Logging & Data Methods

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

Conditions Type

The Conditions type defines criteria that the agent can wait for during durable execution:

Condition Type	Description
`Sleep`	Sleep for a specified duration
`UserEvent`	Wait for a specific user event to be triggered
`Parent`	Wait for parent task completion

Conditions can be combined using Or() for complex conditional logic.

Duration Format

Durations use a subset of Go duration string format with single suffixes only:

Format	Description
`"1s"`	1 second
`"5m"`	5 minutes
`"1h"`	1 hour

icepick.tool - Create individual tools that can be used by agents
icepick.toolbox - Create collections of tools for agents to use
Hatchet Documentation - Learn more about the underlying workflow engine

Get Started

Concepts

Development

Adding to Your Codebase

Patterns

Deployment

API Reference

CLI Reference

Quick Reference

Usage Example

Parameters

Concurrency Type

Returns

Properties

Methods

`run(input, options?)`

`runAndWait(input, options?)`

`runNoWait(input, options?)`

`schedule(enqueueAt, input, options?)`

`delay(duration, input, options?)`

`cron(name, expression, input, options?)`

RunOpts Type

DurableContext

Core Properties

Durable Execution Methods

Execution Control

Logging & Data Methods

Conditions Type

Duration Format

​Quick Reference

​Usage Example

​Parameters

​Concurrency Type

​Returns

​Properties

​Methods

​run(input, options?)

​runAndWait(input, options?)

​runNoWait(input, options?)

​schedule(enqueueAt, input, options?)

​delay(duration, input, options?)

​cron(name, expression, input, options?)

​RunOpts Type

​DurableContext

​Core Properties

​Durable Execution Methods

​Execution Control

​Logging & Data Methods

​Conditions Type

​Duration Format

​Related

Quick Reference

Usage Example

Parameters

Concurrency Type

Returns

Properties

Methods

`run(input, options?)`

`runAndWait(input, options?)`

`runNoWait(input, options?)`

`schedule(enqueueAt, input, options?)`

`delay(duration, input, options?)`

`cron(name, expression, input, options?)`

RunOpts Type

DurableContext

Core Properties

Durable Execution Methods

Execution Control

Logging & Data Methods

Conditions Type

Duration Format

Related