TypeScript SDK Reference

TypeScript SDK Reference

A comprehensive reference for building applications with the Anthropic Agent SDK (TypeScript), enabling programmatic interactions with Claude Code and custom tool integrations.

Installation

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

Quick Start

Core Functions

Example: Basic Query

import { query } from '@anthropic-ai/claude-agent-sdk';

const result = query({
  prompt: "Analyze this code and suggest improvements",
  options: {
    allowedTools: ['Read', 'Grep'],
    model: 'claude-opus'
  }
});

for await (const message of result) {
  if (message.type === 'assistant') {
    console.log(message.message.content);
  }
}

Main Functions Reference

query()

Streams Claude Code responses with full message type support. Returns an async generator of SDKMessage objects.

Parameters:

• prompt: string or async iterable of messages (streaming mode)
• options: Configuration object (see Options below)

Returns: Query object (extends AsyncGenerator<SDKMessage, void>)

Key Methods:

• .interrupt() – Interrupt streaming (streaming mode only)
• .setPermissionMode(mode) – Change permissions dynamically (streaming mode only)

tool()

Creates type-safe MCP tool definitions using Zod schemas. Handlers receive validated inputs and must return CallToolResult.

Parameters:

• name: Tool identifier
• description: Natural language description
• inputSchema: Zod schema defining inputs
• handler: Async function (args: z.infer<Schema>, extra?: unknown) => Promise<CallToolResult>

Returns: SdkMcpToolDefinition<Schema>

createSdkMcpServer()

Creates an in-process MCP server for hosting custom tools. Runs in the same Node.js process—no subprocess overhead.

Parameters:

• name: Server identifier
• version: Optional semantic version
• tools: Array of tool definitions from tool()

Returns: McpSdkServerConfigWithInstance (ready for mcpServers option)

Key Configuration Options

Essential Options

Advanced Options

Message Types Overview

The query() generator yields SDKMessage objects. Common types:

See Message Types Reference for complete definitions.

Types Reference Overview

Core Configuration Types

• Options – Query configuration with 20+ properties (Tools, MCP, permissions, execution)
• PermissionMode – Control execution permissions: 'default', 'acceptEdits', 'bypassPermissions', 'plan'
• SettingSource – Filesystem config scope: 'user', 'project', 'local'

Agent & Tool Types

• AgentDefinition – Subagent config: description, prompt, tools, model override
• SdkMcpToolDefinition – Output of tool() function with Zod schema binding
• McpServerConfig – Union of stdio, SSE, HTTP, or SDK server configs

MCP Server Configuration

Hook Types

• HookEvent – Event names: PreToolUse, PostToolUse, Notification, UserPromptSubmit, SessionStart, SessionEnd, etc.
• HookCallback – Async function receiving hook input and returning decisions
• HookInput – Union of all hook input types; each extends BaseHookInput

See Types Reference for detailed type definitions.

Tool Input/Output Reference

Built-in Tool Inputs

All tool names map to input schemas:

See Tool Reference for complete input/output schemas and examples.

Common Patterns

Streaming with Progress

const result = query({
  prompt: "Your task here",
  options: {
    includePartialMessages: true,
    permissionMode: 'bypassPermissions'
  }
});

for await (const msg of result) {
  if (msg.type === 'stream_event') {
    // Handle streaming events
    console.log('Streaming:', msg.event);
  } else if (msg.type === 'result') {
    console.log('Cost:', msg.total_cost_usd, 'Usage:', msg.usage);
  }
}

Custom MCP Tools

import { tool, createSdkMcpServer, query } from '@anthropic-ai/claude-agent-sdk';
import { z } from 'zod';

const myTool = tool(
  'my-calculator',
  'Add two numbers',
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: 'text', text: `Result: ${a + b}` }]
  })
);

const server = createSdkMcpServer({
  name: 'my-tools',
  tools: [myTool]
});

const result = query({
  prompt: "Use my-calculator to add 5 + 3",
  options: {
    mcpServers: { 'my-tools': server }
  }
});

Loading Project Settings

const result = query({
  prompt: "Add a feature following project conventions",
  options: {
    systemPrompt: {
      type: 'preset',
      preset: 'claude_code'  // Enables Claude Code system prompt
    },
    settingSources: ['project'],  // Load .claude/settings.json & CLAUDE.md
    allowedTools: ['Read', 'Write', 'Edit', 'Bash']
  }
});

Related Resources

• Full API Reference – Complete type definitions and schemas
• Message Types Reference – SDKMessage union types and examples
• Types Reference – Detailed Options, AgentDefinition, PermissionMode docs
• Tool Reference – Input/output schemas for all built-in tools
• SDK Overview – Getting started guide
• Common Workflows – Step-by-step patterns
• CLI Reference – Command-line interface docs