claude-agent-sdk — quality + safety report

---
name: claude-agent-sdk
description: "Anthropic Claude Agent SDK for autonomous agents and multi-step workflows. Use for subagents, tool orchestration, MCP servers, or encountering CLI not found, context length exceeded errors."

metadata:
  keywords:
    - claude agent sdk
    - "@anthropic-ai/claude-agent-sdk"
    - query()
    - createSdkMcpServer
    - AgentDefinition
    - tool()
    - claude subagents
    - mcp servers
    - autonomous agents
    - agentic loops
    - session management
    - permissionMode
    - canUseTool
    - multi-agent orchestration
    - settingSources
    - CLI not found
    - context length exceeded

license: MIT
---
# Claude Agent SDK

**Status**: Production Ready
**Last Updated**: 2025-11-21
**Dependencies**: @anthropic-ai/claude-code, zod
**Latest Versions**: @anthropic-ai/claude-code@2.0.49+, zod@3.23.0+

---

## Quick Start (5 Minutes)

### 1. Install SDK

```bash
bun add @anthropic-ai/claude-agent-sdk zod
```

**Why these packages:**
- `@anthropic-ai/claude-agent-sdk` - Main Agent SDK
- `zod` - Type-safe schema validation for tools

### 2. Set API Key

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```

**CRITICAL:**
- API key required for all agent operations
- Never commit API keys to version control
- Use environment variables

### 3. Basic Query

```typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

const response = query({
  prompt: "Analyze the codebase and suggest improvements",
  options: {
    model: "claude-sonnet-4-5",
    workingDirectory: process.cwd(),
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

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

---

## Secure Installation

Agent SDK packages provide system-level capabilities — verify before installing to prevent unauthorized agent access. Follow supply chain security best practices:

- **Block post-install scripts** — `npm config set ignore-scripts true` (or Bun: disabled by default)
- **Cooldown period** — Wait 7 days for new package versions to be vetted by the community
- **Audit before installing** — Run `socket package score npm <pkg>` or use `socket npm install <pkg>` to check packages

Load the `dependency-upgrade` skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.

## The Complete Claude Agent SDK Reference

## Table of Contents

1. [Core Query API](#core-query-api)
2. [Tool Integration](#tool-integration-built-in--custom)
3. [MCP Servers](#mcp-servers-model-context-protocol)
4. [Subagent Orchestration](#subagent-orchestration)
5. [Session Management](#session-management)
6. [Permission Control](#permission-control)
7. [Filesystem Settings](#filesystem-settings)
8. [Message Types & Streaming](#message-types--streaming)
9. [Error Handling](#error-handling)
10. [Known Issues](#known-issues-prevention)

---

## When to Load References

The skill includes comprehensive reference files for deep dives. Load these when needed:

- **`references/query-api-reference.md`** - Load when configuring query() options, working with message types, understanding filesystem settings, or debugging API behavior
- **`references/mcp-servers-guide.md`** - Load when creating custom tools, integrating external MCP servers, or debugging server connections
- **`references/subagents-patterns.md`** - Load when designing multi-agent systems, orchestrating specialized agents, or optimizing agent workflows
- **`references/session-management.md`** - Load when implementing persistent conversations, forking sessions, or managing long-running interactions
- **`references/permissions-guide.md`** - Load when implementing custom permission logic, securing agent capabilities, or controlling tool access
- **`references/top-errors.md`** - Load when encountering errors, debugging issues, or implementing error handling

---

## Core Query API

The `query()` function is the primary interface for interacting with Claude Code CLI programmatically. It returns an AsyncGenerator that streams messages as the agent works.

**For complete API details, options, and advanced patterns**: Load `references/query-api-reference.md` when working with advanced configurations, message streaming, or filesystem settings.

### Basic Usage

```typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

const response = query({
  prompt: "Review this code for bugs",
  options: {
    model: "claude-sonnet-4-5",        // or "haiku", "opus"
    workingDirectory: "/path/to/project",
    allowedTools: ["Read", "Grep", "Glob"],
    permissionMode: "default"
  }
});

for await (const message of response) {
  // Process streaming messages
}
```

### Model Selection

| Model | ID | Best For | Speed | Capability |
|-------|-----|----------|-------|------------|
| **Haiku** | `"haiku"` | Fast tasks, monitoring | Fastest | Basic |
| **Sonnet** | `"sonnet"` or `"claude-sonnet-4-5"` | Balanced | Medium | High |
| **Opus** | `"opus"` | Complex reasoning | Slowest | Highest |

---

## Tool Integration (Built-in + Custom)

Claude Code provides built-in tools (Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, Task) that can be controlled via `allowedTools` and `disallowedTools` options.

**For complete tool configuration, custom monitoring, and advanced patterns**: Load `references/query-api-reference.md` when implementing tool restrictions or monitoring.

### Allowing/Disallowing Tools

```typescript
// Whitelist approach (recommended)
const response = query({
  prompt: "Analyze code but don't modify anything",
  options: {
    allowedTools: ["Read", "Grep", "Glob"]
    // ONLY these tools can be used
  }
});

// Blacklist approach
const response = query({
  prompt: "Review and fix issues",
  options: {
    disallowedTools: ["Bash"]
    // Everything except Bash allowed
  }
});
```

**CRITICAL**: `allowedTools` = whitelist (only these tools), `disallowedTools` = blacklist (everything except these). If both specified, `allowedTools` wins.

---

## MCP Servers (Model Context Protocol)

MCP servers extend agent capabilities with custom tools via `createSdkMcpServer()` (in-process) or external servers (stdio, HTTP, SSE).

**For complete MCP server implementation guide**: Load `references/mcp-servers-guide.md` when creating custom tools or integrating MCP servers.

**Quick Example**: Create server with `tool(name, description, zodSchema, handler)`, use with `mcpServers` option and `allowedTools: ["mcp__<server>__<tool>"]`

---

## Subagent Orchestration

Specialized agents with focused expertise, custom tools, different models, and dedicated prompts for multi-agent workflows.

**For complete subagent patterns and orchestration strategies**: Load `references/subagents-patterns.md` when designing multi-agent systems.

**AgentDefinition**: Use `agents` option with objects containing `description`, `prompt`, `tools` (optional), `model` (optional)

---

## Session Management

Sessions enable persistent conversations, context preservation, and alternative exploration paths (forking).

**For complete session patterns and workflows**: Load `references/session-management.md` when implementing persistent conversations.

**Usage**: Capture `session_id` from system init message, resume with `resume: sessionId` option, fork with `forkSession: true`

---

## Permission Control

Control agent capabilities with permission modes: `"default"` (standard checks), `"acceptEdits"` (auto-approve edits), `"bypassPermissions"` (skip all checks - use with caution).

**For complete permission patterns and security policies**: Load `references/permissions-guide.md` when implementing custom permission logic.

**Custom Logic**: Use `canUseTool: async (toolName, input) => ({ behavior: "allow" | "deny" | "ask", message?: string })` callback

---

## Filesystem Settings

Control which settings files load via `settingSources` array: `"user"` (~/.claude/settings.json), `"project"` (.claude/settings.json), `"local"` (.claude/settings.local.json).

**For complete configuration and priority rules**: Load `references/query-api-reference.md` when configuring settings sources.

**Default**: `[]` (no settings loaded). **Priority**: Programmatic > local > project > user

---

## Message Types & Streaming

The SDK streams messages: `system` (init/completion), `assistant` (responses), `tool_call` (tool requests), `tool_result` (tool outputs), `error` (failures).

**For complete message type reference and streaming patterns**: Load `references/query-api-reference.md` when implementing advanced message handling.

**Usage**: Process messages in `for await (const message of response)` loop, switch on `message.type`

---

## Error Handling

Common errors: `CLI_NOT_FOUND`, `AUTHENTICATION_FAILED`, `RATE_LIMIT_EXCEEDED`, `CONTEXT_LENGTH_EXCEEDED`, `PERMISSION_DENIED`.

**For complete error catalog with solutions**: Load `references/top-errors.md` when encountering errors or implementing error handling.

**Pattern**: Wrap query in try/catch, check `error.code`, handle `message.type === 'error'` in streaming loop

---

## Known Issues Prevention

This skill prevents **12** documented issues. The top 3 most common:

### Issue #1: CLI Not Found Error
**Error**: `"Claude Code CLI not installed"`
**Prevention**: Install before using SDK: `bun add -g @anthropic-ai/claude-code`

### Issue #2: Authentication Failed
**Error**: `"Invalid API key"`
**Prevention**: Always set `export ANTHROPIC_API_KEY="sk-ant-..."`

### Issue #3: Permission Denied Errors
**Error**: Tool execution blocked
**Prevention**: Use `allowedTools` or custom `canUseTool` callback

**For all 12 errors with complete solutions**: Load `references/top-errors.md` when debugging or implementing error prevention.

---

## Critical Rules

### Always Do

✅ Install Claude Code CLI before using SDK
✅ Set `ANTHROPIC_API_KEY` environment variable
✅ Capture `session_id` from `system` messages for resuming
✅ Use `allowedTools` to restrict agent capabilities
✅ Implement `canUseTool` for custom permission logic
✅ Handle all message types in streaming loop
✅ Use Zod schemas for tool input validation
✅ Set `workingDirectory` for multi-project environments
✅ Test MCP servers in isolation before integration
✅ Use `settingSources: ["project"]` in CI/CD
✅ Monitor tool execution with `tool_call` messages
✅ Implement error handling for all queries

### Never Do

❌ Commit API keys to version control
❌ Use `bypassPermissions` in production (unless sandboxed)
❌ Assume tools executed (check `tool_result` messages)
❌ Ignore error messages in stream
❌ Skip session ID capture if planning to resume
❌ Use duplicate tool names across MCP servers
❌ Allow unrestricted Bash access without `canUseTool`
❌ Load settings from user in CI/CD (`settingSources: ["user"]`)
❌ Trust tool results without validation
❌ Hardcode file paths (use `workingDirectory`)
❌ Use `acceptEdits` mode with untrusted prompts
❌ Skip Zod validation for tool inputs

---

## Dependencies

**Required**:
- `@anthropic-ai/claude-agent-sdk@0.1.0+` - Agent SDK
- `zod@3.23.0+` - Schema validation

**Optional**:
- `@types/node@20.0.0+` - TypeScript types
- `@modelcontextprotocol/sdk@latest` - MCP server development

**System Requirements**:
- Node.js 18.0.0+
- Claude Code CLI (install: `bun add -g @anthropic-ai/claude-code`)
- Valid ANTHROPIC_API_KEY

---

## Official Documentation

- **Agent SDK Overview**: https://docs.claude.com/en/api/agent-sdk/overview
- **TypeScript API**: https://docs.claude.com/en/api/agent-sdk/typescript
- **Python API**: https://docs.claude.com/en/api/agent-sdk/python
- **Model Context Protocol**: https://modelcontextprotocol.io/
- **GitHub (TypeScript)**: https://github.com/anthropics/claude-agent-sdk-typescript
- **GitHub (Python)**: https://github.com/anthropics/claude-agent-sdk-python
- **Context7 Library ID**: /anthropics/claude-agent-sdk-typescript

---

## Package Versions (Verified 2025-10-25

… (truncated)