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 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' 
how to use claude-agent-sdk
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use claude-agent-sdk on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add claude-agent-sdk
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/jezweb/claude-skills --skill claude-agent-sdkcopy
The skills CLI fetches claude-agent-sdk from GitHub repository jezweb/claude-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/claude-agent-sdk
Reload or restart Cursor to activate claude-agent-sdk. Access the skill through slash commands (e.g., /claude-agent-sdk) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?