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:
ParameterTypeRequiredDescription
namestringNoWorker name for identification. Default: “icepick-worker”
registerBaseOrRegisterable[]NoWorkflows to register. If omitted, uses auto-discovery
slotsnumberNoMaximum number of concurrent workflow runs. Default: 100
durableSlotsnumberNoMaximum number of concurrent durable workflow runs. Default: 1,000
labelsWorkerLabelsNoKey-value pairs for worker affinity and routing
handleKillbooleanNoWhether to handle process kill signals gracefully
workflowsBaseWorkflowDeclaration[]NoDirect workflow array (typically handled via register)

​
BaseOrRegisterable Type

The register parameter accepts workflows and registerable objects:
TypeDescription
BaseWorkflowDeclarationIndividual workflow (agent, tool, or Hatchet workflow)
RegisterableObject with a register property that returns workflow arrays
Supported workflow types:

​
WorkerLabels Type

Worker labels for affinity-based assignment and routing:
PropertyTypeDescription
[key]string | numberLabel 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

ParameterDefaultPurpose
slots100Regular workflow concurrency limit
durableSlots1,000Durable 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,
  ],
});