### Execute Example Script

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/examples.md

Runs the example script using ts-node to start the worker.

```bash
npx ts-node example.ts
```

--------------------------------

### Install Icepick CLI and Create Agent

Source: https://github.com/hatchet-dev/icepick/blob/main/README.md

These commands show how to install the Icepick CLI globally and create a new Icepick project from a template to explore an example agent.

```bash
pnpm i -g @hatchet-dev/icepick-cli
icepick create first-agent
```

--------------------------------

### Create a New Icepick Project

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Use the Icepick CLI to create a new project and navigate into its directory. The CLI will guide you through project setup.

```bash
icepick create my-first-agent
cd my-first-agent
```

--------------------------------

### Create Command Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-cli.md

Example of using the 'create' command to initialize a new Icepick project named 'my-research-agent'. This will prompt for further details and create a new directory.

```bash
icepick create my-research-agent
# Prompts for description, author, and template selection
# Creates directory ./my-research-agent/
```

--------------------------------

### Install Icepick SDK

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Install the Icepick SDK using npm. Remember to also install peer dependencies like zod and AI SDKs.

```bash
npm install @hatchet-dev/icepick
npm install zod ai @ai-sdk/openai  # Add peer dependencies
```

--------------------------------

### Install Dependencies

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/examples.md

Installs necessary project dependencies using npm.

```bash
npm install @hatchet-dev/icepick @ai-sdk/openai zod axios
```

--------------------------------

### Client Configuration Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/types.md

Example of creating a ClientConfig object for Icepick initialization, specifying the default language model and connection details.

```typescript
const config: ClientConfig = {
  defaultLanguageModel: openai("gpt-4-turbo"),
  host: "localhost",
  port: 8080,
};
```

--------------------------------

### PickInput Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/types.md

An example demonstrating how to construct a PickInput object. Ensure the prompt is a string and maxTools, if provided, is a number.

```typescript
const input: PickInput = {
  prompt: "Search for information about AI",
  maxTools: 2,
};
```

--------------------------------

### Process Templates Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/template-engine.md

Demonstrates rendering a template file with provided context variables.

```typescript
const processed = processor.processTemplates(
  [{ path: "agent.ts.hbs", content: "export const {{name}} = ..." }],
  { name: "myAgent" }
);
// Returns:
// [{ originalPath: "agent.ts.hbs", content: "export const myAgent = ...", ... }]
```

--------------------------------

### Example Tool Declaration

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/types.md

Illustrates how to declare a 'search' tool with specified input and output schemas and a description.

```typescript
const searchTool: ToolDeclaration<typeof InputSchema, typeof OutputSchema> = 
  icepick.tool({
    name: "search",
    inputSchema: z.object({ query: z.string() }),
    outputSchema: z.object({ results: z.array(z.string()) }),
    description: "Search for information",
    fn: async (input) => ({ results: [] })
  });
```

--------------------------------

### Start MCP Server for Claude

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Use this command to start the MCP server, specifically configured for Claude.

```bash
icepick mcp
```

--------------------------------

### Install Icepick SDK and CLI

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/QUICK_REFERENCE.md

Install the Icepick SDK and CLI using npm. The SDK is for project dependencies, while the CLI is for global command-line access.

```bash
npm install @hatchet-dev/icepick zod ai @ai-sdk/openai
npm install -g @hatchet-dev/icepick-cli
```

--------------------------------

### Verify Icepick CLI Installation

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Verify that the Icepick CLI has been installed correctly by checking its version.

```bash
icepick --version
```

--------------------------------

### Fetch Local Templates Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/template-engine.md

Demonstrates how to use fetchTemplate to retrieve files from a local directory.

```typescript
const files = await fetcher.fetchTemplate({
  type: "local",
  path: "/templates/agent"
});
// Returns files like:
// [
//   { path: "agent.ts.hbs", content: "export const..." },
//   { path: "index.ts.hbs", content: "export { ... }" }
// ]
```

--------------------------------

### Test Tool Locally

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Execute a tool's function directly for quick testing without requiring a full Hatchet setup. This example calls a tool with a 'test' query and logs the result.

```typescript
// Quick test without full Hatchet setup
const tool = icepick.tool({ /* ... */ });
const result = await tool.fn({ query: "test" });
console.log(result);
```

--------------------------------

### Install Icepick CLI

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Install the Icepick Command Line Interface globally using npm or pnpm for easy project management.

```bash
npm install -g @hatchet-dev/icepick-cli
```

```bash
pnpm add -g @hatchet-dev/icepick-cli
```

--------------------------------

### ToolSet Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/types.md

Illustrates how to define a ToolSet with a 'search' tool, specifying its parameters and a description. This is an example of how to structure tool definitions for AI integration.

```typescript
const toolSet: ToolSet = {
  search: {
    parameters: {
      type: "object",
      properties: { query: { type: "string" } }
    },
    description: "Search the web"
  }
};
```

--------------------------------

### StartOptions Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/types.md

Shows how to configure StartOptions for an Icepick worker, setting a custom name and providing an array of agents and toolboxes to register. This is used when initiating a worker instance.

```typescript
const opts: StartOptions = {
  name: "my-worker",
  register: [agent1, toolbox1, agent2],
};
```

--------------------------------

### Plan Agent Example (via Claude)

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/cli-mcp-server.md

Demonstrates how an AI assistant uses the plan_agent tool to retrieve guidelines for creating new agents. It shows the user query, the tool call, and the AI's subsequent response.

```text
User: How do I create a good agent?
Claude: Let me get the planning instructions.
[Calls plan_agent]
→ [Reads: https://icepick.hatchet.run/mcp/mcp-instructions.md]
Claude: Based on the guidelines, here's how to structure your agent...
```

--------------------------------

### Create an Agent with Configuration

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/configuration.md

Example of creating an agent with name, description, input/output schemas, execution timeout, retries, and the agent function.

```typescript
const myAgent = icepick.agent({
  name: "research-agent",
  description: "Performs deep research on topics",
  inputSchema: z.object({
    topic: z.string(),
    depth: z.enum(["shallow", "deep"]),
  }),
  outputSchema: z.object({
    findings: z.array(z.string()),
    summary: z.string(),
  }),
  executionTimeout: "30m",
  retries: 2,
  fn: async (input, ctx) => {
    // Implementation
    return { findings: [], summary: "" };
  },
});
```

--------------------------------

### Instantiate TemplateEngine

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/template-engine.md

Example of creating a new TemplateEngine instance.

```typescript
const engine = new TemplateEngine();
```

--------------------------------

### Example CreateToolboxOpts

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/types.md

Shows how to define the options for creating a toolbox, including a read-only array of tool declarations.

```typescript
const opts: CreateToolboxOpts<readonly [typeof tool1, typeof tool2]> = {
  tools: [tool1, tool2] as const,
};
```

--------------------------------

### Scaffold Tool Example (via Claude)

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/cli-mcp-server.md

Illustrates how an AI assistant like Claude would call the scaffold_tool tool. It shows the user prompt and the tool invocation with parameters.

```text
User: Add a tool to search the web
Claude: I'll create a web search tool for you.
[Calls scaffold_tool with name="web-search"]
→ Tool created in ./src/tools/web-search.tool.ts
```

--------------------------------

### Starting the Icepick MCP Server

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/cli-mcp-server.md

Initializes and connects the MCP server to stdio transport, logging a startup message to stderr.

```typescript
async run() {
  const transport = new StdioServerTransport();
  await this.server.connect(transport);
  console.error("Icepick MCP server running on stdio");
}
```

--------------------------------

### Basic Agent with Tools

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/examples.md

This example demonstrates how to initialize Icepick, define custom tools (search and summarize), create a toolbox, and set up a research agent that uses the toolbox to find and summarize information. It shows how to handle tool selection and execution within an agent.

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

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

// Define tools
const searchTool = icepick.tool({
  name: "search",
  description: "Search for information on the web",
  inputSchema: z.object({
    query: z.string().describe("What to search for"),
  }),
  outputSchema: z.object({
    results: z.array(z.string()),
  }),
  fn: async (input) => {
    // Implement search logic
    return { results: [`Result for: ${input.query}`] };
  },
});

const summarizeTool = icepick.tool({
  name: "summarize",
  description: "Summarize text content",
  inputSchema: z.object({
    text: z.string(),
  }),
  outputSchema: z.object({
    summary: z.string(),
  }),
  fn: async (input) => {
    // Implement summarization logic
    return { summary: `Summary of: ${input.text.substring(0, 50)}...` };
  },
});

// Create toolbox
const toolbox = icepick.toolbox({
  tools: [searchTool, summarizeTool] as const,
});

// Define agent
const researchAgent = icepick.agent({
  name: "research-agent",
  description: "An agent that searches and summarizes information",
  inputSchema: z.object({
    topic: z.string().describe("Topic to research"),
  }),
  outputSchema: z.object({
    summary: z.string(),
  }),
  executionTimeout: "10m",
  fn: async (input, ctx) => {
    // Agent picks and runs tools based on LLM decision
    const result = await toolbox.pickAndRun({
      prompt: `Research the topic: ${input.topic}`,
      maxTools: 2,
    });

    // Type-safe handling of multiple tools
    if (Array.isArray(result)) {
      const summaries = result.map(r => 
        r.name === "summarize" ? r.output.summary : r.output.results.join(", ")
      );
      return { summary: summaries.join(" | ") };
    }

    return {
      summary: result.name === "search" 
        ? result.output.results.join(", ")
        : result.output.summary,
    };
  },
});

// Start worker
const worker = await icepick.start({
  name: "research-worker",
  register: [researchAgent, toolbox],
});

```

--------------------------------

### Enable Verbose Logging

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Initialize Icepick with debug mode enabled to get detailed logs for troubleshooting. This example uses the OpenAI GPT-4 Turbo model.

```typescript
const icepick = Icepick.init(
  {
    defaultLanguageModel: openai("gpt-4-turbo"),
  },
  {
    debug: true,
  }
);
```

--------------------------------

### start Method

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-icepick.md

Registers workflows and starts the worker to process agent and tool executions. This is the entry point for running your Icepick applications.

```APIDOC
## start Method

### Description
Registers workflows and starts the worker to process agent and tool executions.

### Signature
```typescript
async start(options: StartOptions = {}): Promise<Worker>
```

### Parameters
#### options.register
- **register** (Array<BaseOrRegisterable>) - Optional - Workflows/agents/tools to register

#### options.name
- **name** (string) - Optional - Worker name (default: "icepick-worker")

### Returns
A `Worker` instance that has been started.

### Throws
`Error` if no workflows are registered.

### Example
```typescript
const worker = await icepick.start({
  register: [myAgent, myToolbox],
  name: "my-worker",
});
```
```

--------------------------------

### Scaffold Agent Example (via Claude)

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/cli-mcp-server.md

Illustrates how an AI assistant like Claude would call the scaffold_agent tool. It shows the user prompt and the tool invocation with parameters.

```text
User: Create an agent called "web-research" that searches the web
Claude: I'll scaffold a web research agent for you.
[Calls scaffold_agent with name="web-research", description="Searches and summarizes web information"]
→ Agent created in ./src/agents/web-research.agent.ts
```

--------------------------------

### start Method

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-icepick.md

Starts the Icepick worker, enabling it to process tasks and execute agents and tools. This method returns a `Worker` instance.

```APIDOC
## start Method

### Description
Starts the Icepick worker, enabling it to process tasks and execute agents and tools.

### Signature
```typescript
async start(options?: StartOptions): Promise<Worker>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Options Object (StartOptions)
* `concurrency`: `number` - Optional - The number of concurrent workers to start.
* `shutdownSignal`: `NodeJS.Signals` - Optional - The signal to use for shutting down the worker.

### Returns
A `Promise` that resolves to a `Worker` instance.

### Example
```typescript
const worker = await icepick.start({
  concurrency: 4,
});
```
```

--------------------------------

### Agent Declaration Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/types.md

Example of how to declare an agent using AgentDeclaration with Zod schemas for input and output.

```typescript
const agent: AgentDeclaration<typeof InputSchema, typeof OutputSchema> = 
  icepick.agent({
    name: "my-agent",
    inputSchema: z.object({ msg: z.string() }),
    outputSchema: z.object({ result: z.string() }),
    description: "An agent",
    fn: async (input, ctx) => ({ result: input.msg })
  });
```

--------------------------------

### Compile Template Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/template-engine.md

Demonstrates compiling a simple Handlebars template string and rendering it with context.

```typescript
const fn = processor.compile("Hello {{name}}!");
const result = fn({ name: "World" }); // "Hello World!"
```

--------------------------------

### Start the Icepick Worker

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-icepick.md

The `start` method registers workflows, agents, and tools, then initiates the worker process. It can accept an array of items to register and an optional worker name. An error is thrown if no workflows are registered.

```typescript
const worker = await icepick.start({
  register: [myAgent, myToolbox],
  name: "my-worker",
});
```

--------------------------------

### Start Icepick Worker with Auto-Discovery

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/configuration.md

This snippet demonstrates starting an Icepick worker that automatically discovers and registers workflows, agents, or toolboxes that were registered prior to the worker's start.

```typescript
// Or use auto-discovery (if agents/toolboxes registered before start)
const worker = await icepick.start({
  name: "auto-worker",
});
```

--------------------------------

### Toolbox Constructor Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-toolbox.md

Instantiates a new Toolbox with a set of tools and an Icepick client. Ensure 'tool1', 'tool2', 'tool3', and 'icepickClient' are defined elsewhere.

```typescript
const toolbox = new Toolbox(
  { tools: [tool1, tool2, tool3] },
  icepickClient
);
```

--------------------------------

### Successful Tool Creation Response

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/cli-mcp-server.md

Example of a successful response when a tool is created, confirming the tool name.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Tool 'web-search' created successfully."
    }
  ]
}
```

--------------------------------

### Initialize Icepick SDK

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/QUICK_REFERENCE.md

Initialize the Icepick SDK with a default language model. Ensure necessary SDKs like `@ai-sdk/openai` are installed.

```typescript
import { Icepick } from "@hatchet-dev/icepick";
import { openai } from "@ai-sdk/openai";

const icepick = Icepick.init({
  defaultLanguageModel: openai("gpt-4-turbo"),
});
```

--------------------------------

### View Icepick Version

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Check the currently installed version of the Icepick CLI.

```bash
icepick version
```

--------------------------------

### Register Template Partial

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/template-engine.md

Example of registering a 'license' partial and its usage in a template.

```typescript
engine.registerPartial("license", "MIT License - {{year}}");
// Usage in template: {{> license}}
```

--------------------------------

### Initialize Icepick Client and Start Worker

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Initializes the Icepick client with a default language model and starts a worker that registers the defined agent. Ensure your OpenAI API key is set as an environment variable.

```typescript
import { Icepick } from "@hatchet-dev/icepick";
import { openai } from "@ai-sdk/openai";
import { researchAgent } from "./agents/research.agent";

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

icepick.start({
  register: [researchAgent],
  name: "research-worker",
});
```

--------------------------------

### Display Icepick Version

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-cli.md

Prints the installed version of the Hatchet Icepick CLI. This command is useful for verifying the installed version and ensuring compatibility.

```bash
icepick version
# Output: Hatchet Icepick v0.1.26
```

--------------------------------

### Global Option Example: Change Working Directory

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-cli.md

Example of using the --cwd global option to specify a working directory before executing a command.

```bash
icepick --cwd /my/project create
```

--------------------------------

### Example Icepick CLI Security Warning

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-cli.md

This is an example of the warning message displayed by the Icepick CLI when it detects that a command is being run in a sensitive system directory. It advises the user to consider using a dedicated workspace.

```bash
⚠️  Warning: You are about to run icepick in a system directory: /usr/local
   This could create project files in a system location.
   Consider using a dedicated workspace directory instead.
```

--------------------------------

### Icepick Client Methods

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/module-exports.md

The `Icepick` class provides methods for initializing the client, declaring agents and tools, creating toolboxes, and starting the worker.

```APIDOC
## Icepick Class Methods

### `static init(config?, options?, axiosConfig?)`

**Description**: Initializes a new `Icepick` client instance.

### `constructor(config?, options?, axiosConfig?)`

**Description**: Constructs an `Icepick` client instance.

### `agent<InputSchema, OutputSchema>(options)`

**Description**: Declares an agent with specified input and output schemas.

### `tool<Name, InputSchema, OutputSchema>(options)`

**Description**: Declares a tool with a specific name, input, and output schema.

### `toolbox<T>(options)`

**Description**: Creates a `Toolbox` instance for managing a collection of tools.

### `async start(options?)`

**Description**: Starts the workflow worker.
```

--------------------------------

### Start MCP Server

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-cli.md

Launches an MCP server that exposes Icepick tools to AI applications. The server typically runs on stdio and can be configured for use with AI platforms like Claude.

```bash
icepick mcp
# Starts server on stdio
# Can be used with Claude via MCP configuration
```

--------------------------------

### Icepick SDK Methods

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/DELIVERY_SUMMARY.txt

This section details the core methods available on the Icepick SDK client for initializing the SDK, creating agents, defining tools, managing toolboxes, and starting the worker.

```APIDOC
## Icepick SDK Methods

### Description
Provides access to the main functionalities of the Icepick SDK.

### Methods
- **init()**: Initialize SDK.
- **agent(options)**: Create an agent.
- **tool(options)**: Create a tool.
- **toolbox(options)**: Create a toolbox.
- **start(options)**: Start worker.

### Parameters
#### Icepick.agent() Parameters
- **name** (string) - Required - Name of the agent.
- **description** (string) - Required - Description of the agent.
- **schemas** (object) - Required - Schemas for the agent.
- **fn** (function) - Required - The function to execute for the agent.
- **timeout** (number) - Optional - Timeout for agent execution.
- **retries** (number) - Optional - Number of retries for agent execution.

#### Icepick.tool() Parameters
- **name** (string) - Required - Name of the tool.
- **description** (string) - Required - Description of the tool.
- **schemas** (object) - Required - Schemas for the tool.
- **fn** (function) - Required - The function to execute for the tool.
- **retries** (number) - Optional - Number of retries for tool execution.

#### Icepick.toolbox() Parameters
- **tools** (array) - Required - An array of tool definitions.

#### Icepick.start() Parameters
- **name** (string) - Optional - Name of the worker.
- **register** (boolean) - Optional - Whether to register the worker.
```

--------------------------------

### PickAndRun Method Example (Multiple Tools)

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-toolbox.md

Executes multiple tools selected by the language model when 'maxTools' is greater than 1. The method returns an array of results in the order of selection.

```typescript
const results = await toolbox.pickAndRun({
  prompt: "Search for information and summarize it",
  maxTools: 2,
});

// results is an array:
// [
//   { name: "search", output: [...], args: {...} },
//   { name: "summarize", output: "...", args: {...} }
// ]
```

--------------------------------

### List Local Templates

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/template-engine.md

Example of using getLocalTemplates to retrieve the names of available template directories.

```typescript
const templates = await engine.getLocalTemplates("/my/templates");
// Returns: ["agent", "tool", "project"]
```

--------------------------------

### ToolResultMap Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-toolbox.md

Illustrates the ToolResultMap type for a scenario with 'search' and 'summarize' tools, showing the expected structure for each tool's result.

```typescript
type Result =
  | { name: "search"; output: SearchOutput; args: SearchInput }
  | { name: "summarize"; output: SummaryOutput; args: SummaryInput };
```

--------------------------------

### Successful Agent Creation Response

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/cli-mcp-server.md

Example of a successful response when an agent is created, indicating the agent name and file location.

```json
{
  "content": [
    {
      "type": "text",
      "text": "Agent 'research-agent' created successfully\nFiles created in: /project/src/agents"
    }
  ]
}
```

--------------------------------

### Pick Method Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-toolbox.md

Uses the Toolbox's pick method to select relevant tools based on a natural language prompt. Specify 'maxTools' to limit the number of selected tools.

```typescript
const picked = await toolbox.pick({
  prompt: "Search for information about machine learning",
  maxTools: 2,
});

// picked:
// [
//   { name: "search", input: { query: "machine learning" } },
//   { name: "summarize", input: { text: "..." } }
// ]
```

--------------------------------

### PickAndRun Method Example (Single Tool)

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-toolbox.md

Executes a single tool selected by the language model using the pickAndRun method. This is the default behavior when 'maxTools' is omitted or set to 1.

```typescript
const result = await toolbox.pickAndRun({
  prompt: "Calculate the sum of 5 and 10",
});

// result.name === "calculate"
// result.output === 15
// result.args === { a: 5, b: 10 }
```

--------------------------------

### Claude MCP Server Configuration

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/cli-mcp-server.md

Example configuration for Claude to connect to the Icepick MCP server. It specifies the command and arguments to launch the server.

```json
{
  "mcpServers": {
    "icepick": {
      "command": "icepick",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### StartOptions Interface Definition

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/types.md

Defines the options for starting an Icepick worker, including an optional name and a list of workflows, agents, or tools to register. Inherits configuration from CreateWorkerOpts.

```typescript
interface StartOptions extends CreateWorkerOpts {
  name?: string;
  register?: Array<BaseOrRegisterable> | Array<Array<BaseOrRegisterable>>;
}
```

--------------------------------

### CLI Project Creation Flow

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/template-engine.md

Illustrates the sequence of operations when creating a new project using the Icepick CLI. It involves getting project configuration, processing templates, and writing files.

```plaintext
icepick create
  ↓
getProjectConfig() → {name, description, author, template}
  ↓
processTemplate()
  ├─ Fetch templates from template directory
  ├─ Process with context variables
  └─ Write to output directory

```

--------------------------------

### Start an Icepick Worker

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/QUICK_REFERENCE.md

Use this snippet to start a new Icepick worker, registering agents and tools.

```typescript
await icepick.start({
  register: [myAgent, toolbox],
  name: "my-worker",
});
```

--------------------------------

### Create Command Syntax

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-cli.md

Shows the syntax for the 'create' command, which is used to generate a new Icepick project from a template.

```bash
icepick create [name]
```

--------------------------------

### Create New Icepick Project

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Use this command to initialize a new Icepick project in your current directory.

```bash
icepick create my-project
```

--------------------------------

### Start Icepick Worker with Specific Registrations

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/configuration.md

Use this snippet to start an Icepick worker and explicitly register workflows, agents, or toolboxes.

```typescript
const worker = await icepick.start({
  name: "my-agent-worker",
  register: [myAgent, toolbox1, anotherAgent],
});
```

--------------------------------

### Display Help Information

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-cli.md

Provides help documentation for the Icepick CLI. Use global help for general usage or command-specific help for detailed instructions on individual commands.

```bash
icepick --help              # Global help
```

```bash
icepick create --help       # Help for create command
```

```bash
icepick add agent --help    # Help for add agent command
```

--------------------------------

### Configure Language Model API Keys

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Set these environment variables to authenticate with your chosen language model provider. Replace 'sk-...' with your actual API keys.

```bash
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
```

--------------------------------

### Global Options Help

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-cli.md

Displays global options for the Icepick CLI, including changing the working directory and displaying version or help information.

```bash
icepick [options] [command]
```

--------------------------------

### Register Custom Helper

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/template-engine.md

Example of registering a custom 'uppercase' helper function and its usage in a template.

```typescript
engine.registerHelper("uppercase", (str: string) => str.toUpperCase());
// Usage in template: {{uppercase name}}
```

--------------------------------

### IcepickMcpServer Constructor

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/cli-mcp-server.md

Initializes the MCP server with a name, version, and tool capabilities. It also sets up the necessary tool and request handlers.

```typescript
constructor() {
  this.server = new Server(
    {
      name: "icepick-mcp-server",
      version: "1.0.0",
    },
    {
      capabilities: {
        tools: {},
      },
    }
  );
  this.setupToolHandlers();
  this.setupRequestHandlers();
}
```

--------------------------------

### Chaining Tools Sequentially

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Demonstrates how to chain tools by using the output of one tool as the input for the next. This pattern is useful for multi-step processes where the result of an initial action informs subsequent actions.

```typescript
// First: search
const searchResult = await toolbox.pickAndRun({
  prompt: "Find information about topic X",
});

// Second: summarize the results
const summaryResult = await toolbox.pickAndRun({
  prompt: `Summarize: ${searchResult.output.results.join(", ")}`,
});
```

--------------------------------

### pick Method

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-toolbox.md

Uses the language model to select tools from the toolbox that satisfy a prompt. Returns an array of tool names and their generated inputs.

```APIDOC
## pick Method

### Description
Uses the language model to select tools from the toolbox that satisfy a prompt.

### Signature
```typescript
async pick({ prompt, maxTools }: PickInput): Promise<Array<{ name: string; input: any }>>
```

### Parameters
#### Path Parameters
* **prompt** (string) - Required - Natural-language description of what to achieve
* **maxTools** (number) - Optional - Maximum number of tools to select (defaults to 1)

### Response
#### Success Response (200)
* **name** (string) - The name of the selected tool.
* **input** (any) - Generated arguments for the selected tool.

### Response Example
```json
[
  { "name": "search", "input": { "query": "machine learning" } },
  { "name": "summarize", "input": { "text": "..." } }
]
```

### Example
```typescript
const picked = await toolbox.pick({
  prompt: "Search for information about machine learning",
  maxTools: 2,
});
```
```

--------------------------------

### Process Local Templates

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/template-engine.md

Example of using processTemplates to render local templates for an agent, providing context and output options.

```typescript
const templates = await engine.processTemplates(
  { type: "local", path: "/templates/agent" },
  { name: "myAgent", description: "My agent" },
  { outputDir: "/output", force: false }
);
```

--------------------------------

### Path Interpolation Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/template-engine.md

Template file paths can incorporate variables for dynamic path generation. The `.hbs` extension is automatically removed.

```plaintext
{{name}}.agent.ts.hbs  →  myAgent.agent.ts
src/{{type}}s/{{name}}.ts.hbs  →  src/agents/myAgent.ts

```

--------------------------------

### Icepick.init Static Method

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-icepick.md

A factory method to create a new `Icepick` instance. It accepts configuration options for the language model and client settings.

```APIDOC
## Icepick.init Static Method

### Description
Factory method to create a new Icepick instance.

### Signature
```typescript
static init(config?: Partial<ClientConfig>, options?: HatchetClientOptions, axiosConfig?: AxiosRequestConfig): Icepick
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| config | `Partial<ClientConfig>` | No | `{}` | Configuration including `defaultLanguageModel` |
| options | `HatchetClientOptions` | No | — | Hatchet client options |
| axiosConfig | `AxiosRequestConfig` | No | — | Axios configuration |

### Returns
A new `Icepick` instance.

### Example
```typescript
const icepick = Icepick.init({
  defaultLanguageModel: openai("gpt-4-turbo"),
});
```
```

--------------------------------

### Agent Function with DurableContext

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/types.md

Example of an agent function utilizing the 'run' method from DurableContext to execute an asynchronous operation with automatic checkpointing.

```typescript
const agent = icepick.agent({
  fn: async (input, ctx) => {
    const result = await ctx.run(() => someAsyncWork());
    return { result };
  }
});
```

--------------------------------

### Add Tool Command

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-cli.md

Use this command to add a new tool to your project. It will prompt for a description and create the tool file with a kebab-case filename.

```bash
icepick add tool <name>
```

```bash
icepick add tool webSearch
# Prompts for description
# Creates src/tools/web-search.tool.ts
# Updates src/tools/index.ts
```

--------------------------------

### pickAndRun Method

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-toolbox.md

Selects and executes one or more tools from the toolbox based on a prompt. Returns either a single ToolResultMap or an array of ToolResultMap objects.

```APIDOC
## pickAndRun Method

### Description
Selects and executes tools from the toolbox that satisfy a prompt. Can return a single result or an array of results depending on the `maxTools` parameter.

### Signature
```typescript
async pickAndRun(opts: PickInput): Promise<ToolResultMap<T> | ToolResultMap<T>[]>
```

### Parameters
#### Path Parameters
* **opts.prompt** (string) - Required - Natural-language description of what to achieve.
* **opts.maxTools** (number) - Optional - Maximum number of tools to select. If omitted or 1, a single result is returned. If greater than 1, an array of results is returned.

### Response
#### Success Response (200)
* **name** (string) - The name of the executed tool.
* **output** (any) - The result of the tool execution.
* **args** (any) - The arguments passed to the tool.

### Response Example (Single Tool)
```json
{
  "name": "calculate",
  "output": 15,
  "args": { "a": 5, "b": 10 }
}
```

### Response Example (Multiple Tools)
```json
[
  { "name": "search", "output": [...], "args": {...} },
  { "name": "summarize", "output": "...", "args": {...} }
]
```

### Example (Single Tool)
```typescript
const result = await toolbox.pickAndRun({
  prompt: "Calculate the sum of 5 and 10",
});
```

### Example (Multiple Tools)
```typescript
const results = await toolbox.pickAndRun({
  prompt: "Search for information and summarize it",
  maxTools: 2,
});
```
```

--------------------------------

### Run the Icepick Worker

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Execute the TypeScript file to start the Icepick worker. This worker will register your agent with Hatchet and begin processing tasks.

```bash
npx ts-node src/index.ts
```

--------------------------------

### Add Agent Command

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-cli.md

Use this command to add a new agent to your project. It will prompt for a description and create the agent file.

```bash
icepick add agent <name>
```

```bash
icepick add agent research-agent
# Prompts for description
# Creates src/agents/research-agent.agent.ts
# Updates src/agents/index.ts
```

--------------------------------

### Durable Execution Flow (Agents)

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/architecture.md

Illustrates the step-by-step execution of an agent using durable workflows, including automatic checkpointing for recovery.

```text
Agent Start
  ├─ Run Step 1
  ├─ Checkpoint
  ├─ Run Step 2  (if machine crashes, replay 1+2 from checkpoint)
  ├─ Checkpoint
  └─ Return Result
```

--------------------------------

### Configure Tool Retries

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Set the number of times a tool should be retried upon failure. This example configures the tool to retry up to 3 times.

```typescript
const tool = icepick.tool({
  retries: 3,  // Retry up to 3 times on failure
  // ...
});
```

--------------------------------

### TemplateEngine Constructor

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/template-engine.md

Creates a new instance of the TemplateEngine with default fetcher and processor.

```APIDOC
## TemplateEngine Constructor

### Description
Creates a new template engine instance with default fetcher and processor.

### Method
```typescript
constructor()
```

### Example
```typescript
const engine = new TemplateEngine();
```
```

--------------------------------

### Set Agent Execution Timeout

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Configure the maximum time an agent is allowed to run before being terminated. This example sets the timeout to 15 minutes.

```typescript
const agent = icepick.agent({
  executionTimeout: "15m",  // 15 minutes
  // ...
});
```

--------------------------------

### ToolResultMap Example

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/types.md

Illustrates how to handle the ToolResultMap discriminated union. Use conditional checks on the 'name' property to access the correct output and arguments for each tool.

```typescript
const result = await toolbox.pickAndRun({ prompt });

// result is:
// { name: "search"; output: string[]; args: { query: string } }
// | { name: "summarize"; output: string; args: { text: string } }

if (result.name === "search") {
  // result.output: string[]
  // result.args: { query: string }
} else if (result.name === "summarize") {
  // result.output: string
  // result.args: { text: string }
}
```

--------------------------------

### Using Multiple Tools in a Toolbox

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/getting-started.md

Instantiate a toolbox with multiple tools and use `pickAndRun` to let the LLM select one or more tools based on the prompt. Ensure tools are correctly typed as `as const` for optimal type inference.

```typescript
const toolbox = icepick.toolbox({
  tools: [searchTool, summarizeTool, extractTool] as const,
});

// Let LLM choose one tool
const result = await toolbox.pickAndRun({
  prompt: "Search and summarize information about AI",
});

// Or multiple tools
const results = await toolbox.pickAndRun({
  prompt: "Search and summarize",
  maxTools: 2,
});
```

--------------------------------

### Retry Configuration for Tools

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/configuration.md

Configure automatic retries for a tool to handle transient failures. This example sets the tool to retry up to 3 times on failure.

```typescript
const tool = icepick.tool({
  name: "external-api",
  // ... other options
  retries: 3, // Retry up to 3 times on failure
});
```

--------------------------------

### Icepick Client Class

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/module-exports.md

Defines the Icepick client class, its static initialization method, constructor, and methods for agent, tool, toolbox creation, and starting the worker.

```typescript
export class Icepick extends Hatchet {
  static init(config?, options?, axiosConfig?): Icepick
  constructor(config?, options?, axiosConfig?)
  agent<InputSchema, OutputSchema>(options): AgentDeclaration<InputSchema, OutputSchema>
  tool<Name, InputSchema, OutputSchema>(options): ToolDeclaration<InputSchema, OutputSchema> & { name: Name }
  toolbox<T>(options): Toolbox<T>
  async start(options?): Promise<Worker>
}
```

--------------------------------

### Icepick Constructor

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/api-reference-icepick.md

Initializes a new Icepick client instance. It requires a `defaultLanguageModel` to be provided in the configuration.

```APIDOC
## Icepick Constructor

### Description
Initializes a new Icepick client instance.

### Signature
```typescript
constructor(config?: Partial<ClientConfig>, options?: HatchetClientOptions, axiosConfig?: AxiosRequestConfig)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| config | `Partial<ClientConfig>` | No | `{}` | Configuration object including `defaultLanguageModel` |
| options | `HatchetClientOptions` | No | — | Hatchet client options for connection settings |
| axiosConfig | `AxiosRequestConfig` | No | — | Axios HTTP client configuration |

### Throws
`Error` if `defaultLanguageModel` is not provided in config.

### Example
```typescript
import { icepick } from "@hatchet-dev/icepick";
import { openai } from "@ai-sdk/openai";

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

--------------------------------

### Register a Custom Handlebars Helper

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/architecture.md

Register custom Handlebars helpers with the CLI template engine to extend its functionality. This example shows how to create an 'uppercase' helper.

```typescript
engine.registerHelper("uppercase", (str) => str.toUpperCase());
```

--------------------------------

### Use Toolbox to Run Tools

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/QUICK_REFERENCE.md

Execute tools using a toolbox. `pickAndRun` can execute a single tool or multiple tools based on the prompt and `maxTools` configuration.

```typescript
// Single tool
const result = await toolbox.pickAndRun({ prompt: "search for X" });
// result.name, result.output, result.args

// Multiple tools
const results = await toolbox.pickAndRun({
  prompt: "search and summarize X",
  maxTools: 2,
});
// results is array
```

--------------------------------

### CLI Imports for Programmatic Use

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/module-exports.md

Imports CLI functions for programmatic use, such as creating agents, tools, or starting the MCP. These are typically used for scripting or build processes.

```typescript
// Direct imports for programmatic use
import { createAgent } from "@hatchet-dev/icepick-cli/dist/commands/add-agent"
import { createTool } from "@hatchet-dev/icepick-cli/dist/commands/add-tool"
import { create } from "@hatchet-dev/icepick-cli/dist/commands/create"
import { startMcp } from "@hatchet-dev/icepick-cli/dist/commands/mcp"
```

--------------------------------

### Standard Execution Flow (Tools)

Source: https://github.com/hatchet-dev/icepick/blob/main/_autodocs/architecture.md

Depicts the execution flow for tools, which run as standard tasks without durability, emphasizing lower latency and simpler semantics.

```text
Tool Start
  ├─ Run Implementation
  └─ Return Result
```