claude-agent-sdk-typescript

Claude Agent SDK — TypeScript Guide

Production guidance for building AI agents with the Claude Agent SDK in TypeScript.

Naming: The Claude Code SDK was renamed to the Claude Agent SDK (v0.1.0+). Package: npm install @anthropic-ai/claude-agent-sdk · Import: import { query } from "@anthropic-ai/claude-agent-sdk"

Quick Reference — Two Interaction Modes

1. query() — Stateless, One-Shot

Best for: independent tasks, automation scripts, CI pipelines.

import { query, type ClaudeAgentOptions } from "@anthropic-ai/claude-agent-sdk";

const options: ClaudeAgentOptions = {
  allowedTools: ["Read", "Edit", "Glob"],
  permissionMode: "acceptEdits",
};

for await (const message of query({
  prompt: "Review utils.ts for bugs. Fix any issues you find.",
  options,
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
      else if ("name" in block) console.log(`Tool: ${block.name}`);
    }
  }
  if (message.type === "result") {
    console.log(`Done: ${message.subtype}`);
  }
}

2. ClaudeSDKClient — Stateful, Multi-Turn

Best for: conversations, follow-up questions, interactive apps.

import { ClaudeSDKClient } from "@anthropic-ai/claude-agent-sdk";

const client = new ClaudeSDKClient({
  options: {
    allowedTools: ["Read", "Write", "Bash"],
    permissionMode: "acceptEdits",
  },
});

try {
  await client.query("Analyze the codebase structure");
  for await (const msg of client.receiveMessages()) {
    console.log(msg);
  }
  // Continue the conversation with context preserved
  await client.query("Now refactor the largest file you found");
  for await (const msg of client.receiveMessages()) {
    console.log(msg);
  }
} finally {
  await client.close();
}

ClaudeAgentOptions — Complete Configuration

All options are optional. Key fields (all camelCase):

Field	Type	Description
allowedTools	string[]	Tools Claude can use. See Built-in Tools below.
disallowedTools	string[]	Explicitly block specific tools.
permissionMode	string	"default", "acceptEdits", or "bypassPermissions".
systemPrompt	string | object	Custom instructions. Use { type: "preset", preset: "claude_code" } for CC default.
model	string	e.g. "sonnet", "opus", "haiku", or full model string.
cwd	string	Working directory for the agent.
maxTurns	number	Maximum agentic loop iterations.
settingSources	string[]	["user", "project"] to load Skills/CLAUDE.md from filesystem.
mcpServers	Record<string, McpServerConfig>	MCP server configurations.
agents	Record<string, AgentDefinition>	Named subagent definitions.
hooks	object	Lifecycle hook callbacks.