name: claude-agent-sdk-ts
description: Build AI agents with Claude Agent SDK in TypeScript. Covers V1 query() API for batch workflows and V2 session API for interactive apps. Includes tool configuration, hooks, MCP servers, and multi-turn patterns.

TypeScript Claude Agent SDK Builder

Build AI agents using the Claude Agent SDK in TypeScript by referencing code snippets that demonstrate both V1 (query()) and V2 (session-based) API patterns.

How It Works

1. Choose your API: V1 for scripts/batch processing, V2 for interactive apps
2. Browse the snippet catalog below or in snippets/
3. Copy the snippets you need into your project
4. Customize the copied code for your use case

Snippets are bundled in this skill's snippets/ directory.

Authentication

The Claude Agent SDK automatically uses Claude Code's authentication - no API key configuration required if you're logged into Claude Code.

How it works:
1. The SDK looks for OAuth tokens in ~/.claude/ (created when you run claude login)
2. Falls back to ANTHROPIC_API_KEY environment variable if set
3. No code changes needed - authentication is handled automatically

Check your auth status:

claude auth status

If not authenticated:

claude login

Alternative Providers (Bedrock, Vertex AI, Azure)

The SDK also supports cloud provider APIs. Set environment variables:

Amazon Bedrock:

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-west-2
export AWS_PROFILE=your-profile  # Optional: specify named credentials profile
# Or uses default AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or IAM role)

Google Vertex AI:

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id
# Uses your Google Cloud credentials

Azure:

export CLAUDE_CODE_USE_AZURE=1
export AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
# Uses your Azure credentials

Note: If deploying to a server without Claude Code, set ANTHROPIC_API_KEY in your environment (or use Bedrock/Vertex/Azure as above).

When to Use Claude Agent SDK

Use Claude Agent SDK when you want:
- Quick setup with minimal boilerplate
- Out-of-the-box Claude Code capabilities
- Pre-built tool ecosystem with MCP server integration
- Session management and multi-turn conversations
- Hook system for tool auditing and control

Do NOT use Claude Agent SDK when you need:
- Control over temperature, top_p, top_k, or other advanced sampling parameters
- Direct control over the underlying API request/response
- Non-Claude models

Quick Start Decision Trees

Which API Should I Use?

Building a script or batch processor?
  └─> V1 query() API
      - Single-shot execution
      - Simpler async iteration
      - Good for: CLI tools, automation scripts, one-off tasks

Building an interactive application?
  └─> V2 session API
      - Multi-turn conversations with context
      - Session persistence/resume
      - Good for: Chat apps, web services, persistent assistants

Need quick one-shot queries?
  └─> V2 unstable_v2_prompt()
      - Convenience function, returns result directly
      - No message iteration needed

How Should I Configure Tools?

Want full Claude Code capabilities?
  └─> Use tools: { type: 'preset', preset: 'claude_code' }

Need specific tool subset?
  └─> Use allowedTools: ['Bash', 'Read', 'Write', ...]

Need custom tools?
  └─> Use createSdkMcpServer() with tool() helper
      Then: mcpServers: { 'my-tools': customServer }

Do I Need Hooks?

Need to audit/log tool usage?
  └─> Use PostToolUse hooks

Need to block dangerous operations?
  └─> Use PreToolUse hooks with decision: 'block'

Need to validate tool inputs?
  └─> Use PreToolUse hooks for validation

Building a Chat UI?

Need to persist chat history?
  ├─> Want a database → persistence-sqlite
  └─> Want simple files → persistence-jsonl

Need user approval for tool calls?
  └─> Use ui-tool-approval (PreToolUse hook with WebSocket)

Want to show tool call activity?
  └─> Use ui-tool-history (extract events from stream)

Need everything integrated?
  └─> Use ui-websocket-chat (complete example)

Phase 1: Research

1.1 Understand Your Use Case

Before writing code, understand:
- Is this a one-shot script or multi-turn application?
- What tools does the agent need access to?
- Do you need to control/audit tool usage?
- Does the agent need to persist conversation state?

1.2 Browse Available Snippets

Review the snippet catalog below to identify patterns that match your needs:

1.3 Check SDK Version

The SDK evolves quickly. Check the latest version:

npm info @anthropic-ai/claude-agent-sdk version

Note: V2 APIs are prefixed with unstable_v2_ and may change between versions.

Phase 2: Implement

2.1 Initialize Project

mkdir my-agent && cd my-agent
npm init -y
npm install @anthropic-ai/claude-agent-sdk zod
npm install -D typescript @types/node
npx tsc --init

Update tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  }
}

Update package.json:

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

2.2 Add Snippets

Copy snippets from this skill's snippets/ directory into your project. The snippets are organized by category:

snippets/
├── agent-v1/                 # V1 query() API patterns
│   ├── basic-query.ts
│   ├── query-with-tools.ts
│   ├── query-with-system-prompt.ts
│   └── query-with-queue.ts
├── agent-v2/                 # V2 session API patterns
│   ├── basic-session.ts
│   ├── multi-turn.ts
│   ├── one-shot.ts
│   └── session-resume.ts
├── tools/                    # Tool configuration
│   ├── allowed-tools.ts
│   ├── custom-mcp-server.ts
│   └── tool-registration.ts
├── hooks/                    # Pre/Post tool hooks
│   ├── pre-tool-use.ts
│   └── post-tool-use.ts
├── config/                   # Settings and configuration
│   ├── settings-sources.ts
│   ├── model-selection.ts
│   └── working-directory.ts
├── patterns/                 # Advanced patterns
│   ├── message-queue.ts
│   ├── ai-client-wrapper.ts
│   ├── websocket-session.ts
│   └── subagent-task.ts
├── persistence/              # Chat persistence
│   ├── chat-store-sqlite.ts
│   └── chat-store-jsonl.ts
└── ui/                       # UI integration
    ├── tool-approval-hook.ts
    ├── tool-history-stream.ts
    └── websocket-chat-session.ts

Copy snippets directly:

cp snippets/agent-v1/basic-query.ts /path/to/my-agent/src/
cp snippets/tools/allowed-tools.ts /path/to/my-agent/src/

2.3 Customize and Integrate

Each snippet includes:
- Source attribution with documentation links
- Working code ready to customize

Modify the copied code:
1. Update prompts and system messages
2. Configure allowed/disallowed tools
3. Add custom hooks if needed
4. Integrate with your application logic

Phase 3: Test

3.1 Build and Run

npm run build
npm start

3.2 Debug Output

Add message logging to see what the agent is doing:

for await (const message of q) {
  console.log(JSON.stringify(message, null, 2));
}

3.3 Quality Checklist

• [ ] Agent responds appropriately to prompts
• [ ] Tools are correctly restricted (if applicable)
• [ ] Hooks fire and behave as expected
• [ ] Error handling works for common failures
• [ ] Cost tracking shows expected usage
• [ ] Session persistence works (V2 only)

3.4 Common Issues

Authentication errors / "Unauthorized"
- Run claude auth status to check if logged in
- Run claude login if not authenticated
- For servers: set ANTHROPIC_API_KEY environment variable

"Cannot find module '@anthropic-ai/claude-agent-sdk'"
- Ensure you installed the SDK: npm install @anthropic-ai/claude-agent-sdk

"await using" syntax error
- Requires TypeScript 5.2+ with target: "ES2022" or higher
- Alternative: manually call session[Symbol.asyncDispose]() in finally block

Tool calls fail silently
- Check allowedTools includes the tool being called
- Check disallowedTools doesn't block it

Agent doesn't see .claude/ settings
- Add settingSources: ['project', 'local'] to options
- Ensure cwd points to directory containing .claude/

Available Snippets Catalog

V1: Query-based API

V2: Session-based API

Tool Configuration

Hooks

Configuration

Advanced Patterns

Chat Persistence

UI Integration

Related Skills

This skill focuses on Claude agents that use MCP servers. See also:

When to use each:
- claude-agent-sdk-ts: Out-of-the-box Claude agent when you don't need sampling, elicitation, or logging
- claude-agent-ui-ts: Adding a web UI with real-time chat and tool approval to your agent
- mcp-client-ts: Sophisticated modular agents or apps needing full MCP control
- mcp-server-ts: Building the MCP servers themselves

Claude Agent SDK MCP Capabilities (verified via everything-server test):

For sampling, elicitation, logging, or prompts support, use mcp-client-ts to build a custom client.

Reference Files

For deeper guidance, load these reference documents:

• Agent SDK API Reference - V1 and V2 API documentation, types, options
• Agent SDK Patterns - Best practices, when to use V1 vs V2, common patterns

External Resources

• Claude Agent SDK Repository - Official SDK source
• Claude Agent SDK Documentation - Official documentation
• Claude Code - Claude Code CLI (SDK is based on this)