Claude Agent SDK setup guide

The Claude Agent SDK gives you the same tools, agent loop, and context management that power Claude Code. Combined with Trigger.dev, you get durable execution, automatic retries, and full observability for your agents.

Setup

This guide assumes you are working with an existing Trigger.dev project. Follow our quickstart to get set up if you don’t have a project yet.

Install the Claude Agent SDK

npm

npm install @anthropic-ai/claude-agent-sdk

Configure trigger.config.ts

Add the SDK to the external array so it’s not bundled:

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: process.env.TRIGGER_PROJECT_REF!,
  build: {
    external: ["@anthropic-ai/claude-agent-sdk"],
  },
  machine: "small-2x",
});

Adding packages to external prevents them from being bundled, which is necessary for the Claude Agent SDK. See the build configuration docs for more details.

Set your API key

Add your Anthropic API key to your environment variables. The SDK reads it automatically.

ANTHROPIC_API_KEY=sk-ant-...

You can set this in the Trigger.dev dashboard under Environment Variables, or in your .env file for local development.

Create your first agent task

This example creates a task where Claude generates code in an empty workspace. The agent will create files based on your prompt:

trigger/claude-agent.ts

import { query } from "@anthropic-ai/claude-agent-sdk";
import { schemaTask, logger } from "@trigger.dev/sdk";
import { mkdtemp, rm, readdir } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { z } from "zod";

export const codeGenerator = schemaTask({
  id: "code-generator",
  schema: z.object({
    prompt: z.string(),
  }),
  run: async ({ prompt }, { signal }) => {
    const abortController = new AbortController();
    signal.addEventListener("abort", () => abortController.abort());

    // Create an empty workspace for the agent
    // The agent will create files here based on the prompt
    const workDir = await mkdtemp(join(tmpdir(), "claude-agent-"));
    logger.info("Created workspace", { workDir });

    try {
      const result = query({
        prompt,
        options: {
          model: "claude-sonnet-4-20250514",
          abortController,
          cwd: workDir,
          maxTurns: 10,
          permissionMode: "acceptEdits",
          allowedTools: ["Read", "Edit", "Write", "Glob"],
        },
      });

      for await (const message of result) {
        logger.info("Agent message", { type: message.type });
      }

      // See what files Claude created
      const files = await readdir(workDir, { recursive: true });
      logger.info("Files created", { files });

      return { filesCreated: files };
    } finally {
      await rm(workDir, { recursive: true, force: true });
    }
  },
});

Run the dev server

npx trigger.dev@latest dev

Test your agent

Go to the Trigger.dev dashboard, find your code-generator task, and trigger it with a test payload:

{
  "prompt": "Create a Node.js project with a fibonacci.ts file containing a function to calculate fibonacci numbers, and a fibonacci.test.ts file with tests."
}

How it works

The query() function runs Claude in an agentic loop where it can:

Read files - Explore codebases with Read, Grep, and Glob tools
Edit files - Modify code with Edit and Write tools
Run commands - Execute shell commands with Bash tool (if enabled)
Think step by step - Use extended thinking for complex problems

The agent continues until it completes the task or reaches maxTurns.

Permission modes

Mode	What it does
`"default"`	Asks for approval on potentially dangerous operations
`"acceptEdits"`	Auto-approves file operations, asks for bash/network
`"bypassPermissions"`	Skips all safety checks (not recommended)

Available tools

allowedTools: [
  "Task", // Planning and task management
  "Glob", // Find files by pattern
  "Grep", // Search file contents
  "Read", // Read file contents
  "Edit", // Edit existing files
  "Write", // Create new files
  "Bash", // Run shell commands
  "TodoRead", // Read todo list
  "TodoWrite", // Update todo list
];

GitHub repo

View the Claude Agent SDK + Trigger.dev example

A complete example with two agent patterns: basic safe code generation and advanced with bash execution.

Example projects using the Claude Agent SDK

Claude changelog generator

Generate changelogs from git commits using custom MCP tools.

Claude GitHub wiki agent

Analyze repositories and answer questions with real-time streaming.

Learn more

Claude Agent SDK docs – Official Anthropic documentation
Trigger.dev Realtime – Stream agent progress to your frontend
Waitpoints – Add human-in-the-loop approval steps

​Setup

​How it works

​Permission modes

​Available tools

​GitHub repo

View the Claude Agent SDK + Trigger.dev example

​Example projects using the Claude Agent SDK

Claude changelog generator

Claude GitHub wiki agent

​Learn more

Setup

How it works

Permission modes

Available tools

GitHub repo

Example projects using the Claude Agent SDK

Learn more