Claude Agent Sdk Ts

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, topp, topk, 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:

| Snippet | Description | Best For | |---------|-------------|----------| | v1-basic-query | Simple query() execution | Scripts, automation | | v1-query-tools | Tool allowlist/blocklist | Controlled tool access | | v1-query-system | Custom system prompt | Agent personality/behavior | | v1-query-queue | AsyncIterable for multi-turn | V1 chat applications | | v2-basic-session | Session with send/stream | Interactive apps | | v2-multi-turn | Multi-turn with context | Chat applications | | v2-one-shot | Quick query, direct result | Simple questions | | v2-session-resume | Persist/resume sessions | Long-running assistants | | tools-allowed | Tool configuration | Security, capability control | | tools-custom-mcp | Custom MCP server (tools only) | Domain-specific tools | | tools-registration | Zod-based tool definitions | Type-safe custom tools | | hook-pre-tool | Pre-execution hooks | Blocking, validation | | hook-post-tool | Post-execution hooks | Logging, transformation | | config-settings | Settings sources | Loading .claude/ configs | | config-model | Model selection | Choosing opus/sonnet/haiku | | config-cwd | Working directory | File operation scope | | pattern-message-queue | Message queue class | V1 multi-turn | | pattern-ai-client | Reusable client wrapper | Application architecture | | pattern-websocket | WebSocket integration | Real-time apps | | pattern-subagent | Task tool orchestration | Multi-agent systems | | pattern-task-filesystem | File-based subagent definitions | Production multi-agent | | pattern-self-improving | Agents that persist their own skills | Evolving capabilities | | persistence-sqlite | SQLite chat storage with session resume | Database persistence | | persistence-jsonl | JSONL file-based chat storage | Lightweight persistence | | ui-tool-approval | PreToolUse hook with WebSocket approval | Human-in-the-loop | | ui-tool-history | Tool event extraction for UI display | Activity tracking | | ui-websocket-chat | Complete WebSocket chat session | Full-featured chat UI |

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

| Name | Description | |------|-------------| | v1-basic-query | Simple query() with prompt string, iterate over messages | | v1-query-tools | Configure allowedTools and disallowedTools arrays | | v1-query-system | Custom systemPrompt option for agent behavior | | v1-query-queue | AsyncIterable input for multi-turn conversations |

V2: Session-based API

| Name | Description | |------|-------------| | v2-basic-session | Create session with unstablev2createSession, send() and stream() | | v2-multi-turn | Sequential multi-turn conversation with session context retention | | v2-one-shot | One-shot query using unstablev2prompt convenience function | | v2-session-resume | Persist and resume sessions with unstablev2resumeSession |

Tool Configuration

| Name | Description | |------|-------------| | tools-allowed | Whitelist specific tools with allowedTools configuration | | tools-custom-mcp | Create custom MCP server with createSdkMcpServer (tools only) | | tools-registration | Define tools with Zod schemas using tool() helper function | | tools-custom-skill | Load custom skills from .claude/skills/ via Skill tool | | tools-mcp-server-config | Connect to external MCP servers (stdio, Streamable HTTP) |

Hooks

| Name | Description | |------|-------------| | hook-pre-tool | PreToolUse hooks to block or modify tool calls before execution | | hook-post-tool | PostToolUse hooks to process or transform tool results |

Configuration

| Name | Description | |------|-------------| | config-settings | Configure settingSources array (user, project, local) | | config-model | Model selection options (opus, sonnet, haiku) | | config-cwd | Set working directory (cwd) for file operations |

Advanced Patterns

| Name | Description | |------|-------------| | pattern-message-queue | Async MessageQueue class for multi-turn V1 conversations | | pattern-ai-client | Reusable AIClient wrapper class around query() | | pattern-websocket | WebSocket server with SDK session integration | | pattern-subagent | Task tool pattern for subagent orchestration | | pattern-task-filesystem | File-based subagent definitions in .claude/agents/*.md | | pattern-self-improving | Agents that develop, test, and persist their own reusable skills |

Chat Persistence

| Name | Description | |------|-------------| | persistence-sqlite | SQLite chat storage with session ID tracking for resume | | persistence-jsonl | JSONL file-based storage, no native dependencies |

UI Integration

| Name | Description | |------|-------------| | ui-tool-approval | PreToolUse hook that pauses for WebSocket-based user approval | | ui-tool-history | Extract and format tool events for UI display | | ui-websocket-chat | Complete WebSocket chat session with persistence and approval |

---

Related Skills

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

| Skill | Use When | |-------|----------| | claude-agent-ui-ts | Adding React + WebSocket UI on top of your agent with tool approval | | mcp-server-ts | Building MCP servers with tools, resources, prompts, sampling, tasks | | mcp-client-ts | Building custom MCP clients with full protocol support |

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):

| Capability | Sub-capability | Supported | Verification | |------------|----------------|-----------|--------------| | tools | | Yes | SDK has MCP tool calling | | tools | listChanged | Unverified | | | resources | | Yes | ListMcpResourcesTool, ReadMcpResourceTool | | resources | subscribe | Unverified | | | resources | listChanged | Unverified | | | prompts | | No | No prompt tools in SDK | | roots | | Yes | get-roots-list tool registered | | roots | listChanged | Unverified | | | sampling | | No | trigger-sampling-request NOT registered | | elicitation | | No | trigger-elicitation-request NOT registered | | logging | | No | SDK doesn't expose server logs |

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](./reference/agentsdkapi_reference.md) - V1 and V2 API documentation, types, options
• [Agent SDK Patterns](./reference/agentsdkpatterns.md) - 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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: olaservo
• Source: olaservo/mcp-agent-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.