pickaxe.agent

The pickaxe.agent method creates a new instance of an agent in Pickaxe.

​

Quick Reference

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

​

Usage Example

import { pickaxe } from "@hatchet-dev/pickaxe";
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 = pickaxe.toolbox({
  // See pickaxe.toolbox documentation
  tools: [
    // TODO: Add your tools here
    // Example: myTool,
  ],
});

export const myAgent = pickaxe.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

​

Concurrency Type

​

Returns

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

​

Properties

​

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

​

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

​

Durable Execution Methods

​

Execution Control

​

Logging & Data Methods

​

Conditions Type

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

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:

​

Related

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