--- name: claude-agent-sdk description: | Build autonomous AI agents with Claude Agent SDK. Structured outputs guarantee JSON schema validation, with plugins system and hooks for event-driven workflows. Prevents 14 documented errors.

Use when: building coding agents, SRE systems, security auditors, or troubleshooting CLI not found, structured output validation, session forking errors, MCP config issues, subagent cleanup. user-invocable: true ---

Claude Agent SDK - Structured Outputs & Error Prevention Guide

Package: @anthropic-ai/[email protected] Breaking Changes: v0.1.45 - Structured outputs (Nov 2025), v0.1.0 - No default system prompt, settingSources required

---

What's New in v0.1.45+ (Nov 2025)

Major Features:

1. Structured Outputs (v0.1.45, Nov 14, 2025)

• JSON schema validation - Guarantees responses match exact schemas
• outputFormat parameter - Define output structure with JSON schema or Zod
• Access validated results - Via message.structured_output
• Beta header required: structured-outputs-2025-11-13
• Type safety - Full TypeScript inference with Zod schemas

Example:

import { query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const schema = z.object({
  summary: z.string(),
  sentiment: z.enum(['positive', 'neutral', 'negative']),
  confidence: z.number().min(0).max(1)
});

const response = query({
  prompt: "Analyze this code review feedback",
  options: {
    model: "claude-sonnet-4-5",
    outputFormat: {
      type: "json_schema",
      json_schema: {
        name: "AnalysisResult",
        strict: true,
        schema: zodToJsonSchema(schema)
      }
    }
  }
});

for await (const message of response) {
  if (message.type === 'result' && message.structured_output) {
    // Guaranteed to match schema
    const validated = schema.parse(message.structured_output);
    console.log(`Sentiment: ${validated.sentiment}`);
  }
}

Zod Compatibility (v0.1.71+): SDK supports both Zod v3.24.1+ and Zod v4.0.0+ as peer dependencies. Import remains import { z } from "zod" for either version.

2. Plugins System (v0.1.27)

• plugins array - Load local plugin paths
• Custom plugin support - Extend agent capabilities

3. Hooks System (v0.1.0+)

All 12 Hook Events:

| Hook | When Fired | Use Case | |------|------------|----------| | PreToolUse | Before tool execution | Validate, modify, or block tool calls | | PostToolUse | After tool execution | Log results, trigger side effects | | Notification | Agent notifications | Display status updates | | UserPromptSubmit | User prompt received | Pre-process or validate input | | SubagentStart | Subagent spawned | Track delegation, log context | | SubagentStop | Subagent completed | Aggregate results, cleanup | | PreCompact | Before context compaction | Save state before truncation | | PermissionRequest | Permission needed | Custom approval workflows | | Stop | Agent stopping | Cleanup, final logging | | SessionStart | Session begins | Initialize state | | SessionEnd | Session ends | Persist state, cleanup | | Error | Error occurred | Custom error handling |

Hook Configuration:

const response = query({
  prompt: "...",
  options: {
    hooks: {
      PreToolUse: async (input) => {
        console.log(`Tool: ${input.toolName}`);
        return { allow: true };  // or { allow: false, message: "..." }
      },
      PostToolUse: async (input) => {
        await logToolUsage(input.toolName, input.result);
      }
    }
  }
});

4. Additional Options

• fallbackModel - Automatic model fallback on failures
• maxThinkingTokens - Control extended thinking budget
• strictMcpConfig - Strict MCP configuration validation
• continue - Resume with new prompt (differs from resume)
• permissionMode: 'plan' - New permission mode for planning workflows

📚 Docs: https://platform.claude.com/docs/en/agent-sdk/structured-outputs

---

The Complete Claude Agent SDK Reference

Table of Contents

1. Core Query API
2. Tool Integration
3. MCP Servers
4. Subagent Orchestration
5. Session Management
6. Permission Control
7. Sandbox Settings
8. File Checkpointing
9. Filesystem Settings
10. Query Object Methods
11. Message Types & Streaming
12. Error Handling
13. Known Issues

---

Core Query API

Key signature:

query(prompt: string | AsyncIterable<SDKUserMessage>, options?: Options)
  -> AsyncGenerator<SDKMessage>

Critical Options:

• outputFormat - Structured JSON schema validation (v0.1.45+)
• settingSources - Filesystem settings loading ('user'|'project'|'local')
• canUseTool - Custom permission logic callback
• agents - Programmatic subagent definitions
• mcpServers - MCP server configuration
• permissionMode - 'default'|'acceptEdits'|'bypassPermissions'|'plan'
• betas - Enable beta features (e.g., 1M context window)
• sandbox - Sandbox settings for secure execution
• enableFileCheckpointing - Enable file state snapshots
• systemPrompt - System prompt (string or preset object)

Extended Context (1M Tokens)

Enable 1 million token context window:

const response = query({
  prompt: "Analyze this large codebase",
  options: {
    betas: ['context-1m-2025-08-07'],  // Enable 1M context
    model: "claude-sonnet-4-5"
  }
});

System Prompt Configuration

Two forms of systemPrompt:

// 1. Simple string
systemPrompt: "You are a helpful coding assistant."

// 2. Preset with optional append (preserves Claude Code defaults)
systemPrompt: {
  type: 'preset',
  preset: 'claude_code',
  append: "\n\nAdditional context: Focus on security."
}

Use preset form when you want Claude Code's default behaviors plus custom additions.

---

Tool Integration (Built-in + Custom)

Tool Control:

• allowedTools - Whitelist (takes precedence)
• disallowedTools - Blacklist
• canUseTool - Custom permission callback (see Permission Control section)

Built-in Tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, Task, NotebookEdit, BashOutput, KillBash, ListMcpResources, ReadMcpResource, AskUserQuestion

AskUserQuestion Tool (v0.1.71+)

Enable user interaction during agent execution:

const response = query({
  prompt: "Review and refactor the codebase",
  options: {
    allowedTools: ["Read", "Write", "Edit", "AskUserQuestion"]
  }
});

// Agent can now ask clarifying questions
// Questions appear in message stream as tool_call with name "AskUserQuestion"

Use cases:

• Clarify ambiguous requirements mid-task
• Get user approval before destructive operations
• Present options and get selection

Tools Configuration (v0.1.57+)

Three forms of tool configuration:

// 1. Exact allowlist (string array)
tools: ["Read", "Write", "Grep"]

// 2. Disable all tools (empty array)
tools: []

// 3. Preset with defaults (object form)
tools: { type: 'preset', preset: 'claude_code' }

Note: allowedTools and disallowedTools still work but tools provides more flexibility.

---

MCP Servers (Model Context Protocol)

Server Types:

• In-process - createSdkMcpServer() with tool() definitions
• External - stdio, HTTP, SSE transport

Tool Definition:

tool(name: string, description: string, zodSchema, handler)

Handler Return:

{ content: [{ type: "text", text: "..." }], isError?: boolean }

...