> ## Documentation Index > Fetch the complete documentation index at: https://icepick.hatchet.run/llms.txt > Use this file to discover all available pages before exploring further. # icepick.agent > API reference for icepick.agent. The `icepick.agent` method creates a new instance of an agent in Icepick. ## Quick Reference * **Main execution methods**: [`run()`](#run-input%2C-options%3F), [`runAndWait()`](#runandwait-input%2C-options%3F), [`runNoWait()`](#runnowait-input%2C-options%3F) * **Scheduling methods**: [`schedule()`](#schedule-enqueueat%2C-input%2C-options%3F), [`delay()`](#delay-duration%2C-input%2C-options%3F), [`cron()`](#cron-name%2C-expression%2C-input%2C-options%3F) ## Usage Example ```typescript theme={null} 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, ctx: DurableContext>) => Promise>` | Yes | The main agent function that processes input and returns output. Receives validated input and [DurableContext](#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-type) \| [`Concurrency[]`](#concurrency-type) | 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` object with the following [properties](#properties) and [methods](#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` - The input data for the agent * `options?`: [`RunOpts`](#runopts-type) - Optional configuration for this agent run **Returns:** `Promise>` - 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()`](#runinput-options). Triggers an agent run and waits for the result. **Parameters:** * `input`: `z.infer` - The input data for the agent * `options?`: [`RunOpts`](#runopts-type) - Optional configuration for this agent run **Returns:** `Promise>` - A promise that resolves with the agent result #### `runNoWait(input, options?)` Triggers the agent execution without waiting for completion. **Parameters:** * `input`: `z.infer` - The input data for the agent * `options?`: [`RunOpts`](#runopts-type) - Optional configuration for this agent run **Returns:** `Promise>>` - 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` - The input data for the agent * `options?`: [`RunOpts`](#runopts-type) - Optional configuration for this agent run **Returns:** `Promise` - 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` - The input data for the agent * `options?`: [`RunOpts`](#runopts-type) - Optional configuration for this agent run **Returns:** `Promise` - 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` - The input data for the agent * `options?`: [`RunOpts`](#runopts-type) - Optional configuration for this agent run **Returns:** `Promise` - 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` | 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>` | Pauses execution for a specified duration that persists across restarts | | `waitFor()` | `conditions: [Conditions](#conditions-type) \| [Conditions[]](#conditions-type)` | `Promise>` | Waits for specific conditions to be met, persisting across failures | ### Execution Control | Method | Parameters | Returns | Description | | ------------------ | ----------------------- | --------------- | ---------------------------------------------------------- | | `cancel()` | None | `Promise` | Cancels the current task | | `refreshTimeout()` | `incrementBy: Duration` | `Promise` | 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` | Streams data from the current task run | | `additionalMetadata()` | None | `Record` | Retrieves additional metadata | | `errors()` | None | `Record` | 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` | 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 | ## Related * [`icepick.tool`](/api-reference/tool) - Create individual tools that can be used by agents * [`icepick.toolbox`](/api-reference/toolbox) - Create collections of tools for agents to use * [Hatchet Documentation](https://docs.hatchet.run) - Learn more about the underlying workflow engine