icepick.start

The icepick.start method starts the Icepick worker to process agents, tools, and toolboxes. It automatically discovers and registers your workflows or accepts explicit registration.

Quick Reference

Auto-discovery: Automatically finds agents, tools, and toolboxes created with icepick.agent(), icepick.tool(), and icepick.toolbox()
Explicit registration: Register specific workflows using the register parameter
Worker configuration: Configure worker slots, labels, and other runtime options

Usage Example

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

// Initialize Icepick client
const client = icepick.init({
  defaultLanguageModel: openai("gpt-4"),
});

// Create your agents and tools
const searchTool = client.tool({
  name: "search-tool",
  description: "Searches for information",
  inputSchema: z.object({
    query: z.string().describe("The search query"),
  }),
  outputSchema: z.object({
    results: z.array(z.string()).describe("Search results"),
  }),
  fn: async (input) => {
    // Implementation here
    return { results: [`Results for: ${input.query}`] };
  },
});

const myAgent = client.agent({
  name: "search-agent",
  description: "An agent that can search for information",
  inputSchema: z.object({
    message: z.string().describe("User's search request"),
  }),
  outputSchema: z.object({
    response: z.string().describe("Agent's response"),
  }),
  fn: async (input, ctx) => {
    // Agent implementation
    return { response: `Processed: ${input.message}` };
  },
});

// Start with auto-discovery (recommended)
await client.start();

// Or start with explicit registration
await client.start({
  register: [myAgent, searchTool],
});

// Or start with worker configuration
await client.start({
  name: "production-worker",
  slots: 50,
  durableSlots: 500,
  labels: {
    environment: "production",
    region: "us-east-1",
  },
  register: [myAgent, searchTool],
});

Parameters

The start() method accepts a single optional options parameter with the following properties:

Parameter	Type	Required	Description
`name`	`string`	No	Worker name for identification. Default: “icepick-worker”
`register`	`BaseOrRegisterable[]`	No	Workflows to register. If omitted, uses auto-discovery
`slots`	`number`	No	Maximum number of concurrent workflow runs. Default: 100
`durableSlots`	`number`	No	Maximum number of concurrent durable workflow runs. Default: 1,000
`labels`	`WorkerLabels`	No	Key-value pairs for worker affinity and routing
`handleKill`	`boolean`	No	Whether to handle process kill signals gracefully
`workflows`	`BaseWorkflowDeclaration[]`	No	Direct workflow array (typically handled via `register`)

BaseOrRegisterable Type

The register parameter accepts workflows and registerable objects:

Type	Description
`BaseWorkflowDeclaration`	Individual workflow (agent, tool, or Hatchet workflow)
`Registerable`	Object with a `register` property that returns workflow arrays

Supported workflow types:

Agents created with icepick.agent()
Tools created with icepick.tool()
Toolboxes created with icepick.toolbox()
Hatchet workflows created with the Hatchet SDK

WorkerLabels Type

Worker labels for affinity-based assignment and routing:

Property	Type	Description
`[key]`	`string \| number`	Label key-value pairs for worker classification

Common label examples:

{
  environment: "production",
  region: "us-east-1",
  tier: "premium",
  version: "1.0.0"
}

Returns

Type: Promise<undefined | void[]> Returns a promise that resolves when the worker starts successfully. The exact return value depends on the underlying Hatchet worker implementation.

Auto-Discovery

When register is omitted, Icepick automatically discovers workflows from an internal registry that gets populated when you create:

Agents: Added when calling icepick.agent()
Tools: Added when calling icepick.tool()
Toolboxes: Added when calling icepick.toolbox()

// These are automatically registered
const myAgent = icepick.agent({...});
const myTool = icepick.tool({...});
const myToolbox = icepick.toolbox({...});

// Auto-discovery finds all three
await icepick.start(); // Registers myAgent, myTool, and myToolbox

Worker Configuration

Concurrency Control

Parameter	Default	Purpose
`slots`	100	Regular workflow concurrency limit
`durableSlots`	1,000	Durable workflow concurrency limit

Worker Identification

name: Identifies the worker in Hatchet dashboard and logs
labels: Used for workflow routing and worker affinity

Examples

Basic Auto-Discovery

// Create workflows
const agent = icepick.agent({...});
const tool = icepick.tool({...});

// Start automatically discovers both
await icepick.start();

Explicit Registration

await icepick.start({
  register: [
    myAgent,
    myTool,
    myToolbox,
    // Can mix with Hatchet workflows
    someHatchetWorkflow,
  ],
});

icepick.agent - Create agents that get auto-discovered
icepick.tool - Create tools that get auto-discovered
icepick.toolbox - Create toolboxes that get auto-discovered
Hatchet Documentation - Learn more about the underlying workflow engine and worker configuration

Get Started

Concepts

Development

Adding to Your Codebase

Patterns

Deployment

API Reference

CLI Reference

Quick Reference

Usage Example

Parameters

BaseOrRegisterable Type

WorkerLabels Type

Returns

Auto-Discovery

Worker Configuration

Concurrency Control

Worker Identification

Examples

Basic Auto-Discovery

Explicit Registration

​Quick Reference

​Usage Example

​Parameters

​BaseOrRegisterable Type

​WorkerLabels Type

​Returns

​Auto-Discovery

​Worker Configuration

​Concurrency Control

​Worker Identification

​Examples

​Basic Auto-Discovery

​Explicit Registration

​Related

Quick Reference

Usage Example

Parameters

BaseOrRegisterable Type

WorkerLabels Type

Returns

Auto-Discovery

Worker Configuration

Concurrency Control

Worker Identification

Examples

Basic Auto-Discovery

Explicit Registration

Related