/ai-provider-anthropic-sdk

name: ai-provider-anthropic-sdk
description: Official Anthropic SDK patterns for TypeScript/Node.js — client setup, Messages API, streaming, tool use, vision, extended thinking, structured outputs, prompt caching, batch API, and production best practices

Anthropic SDK Patterns

> **Quick Guide:** Use the official `@anthropic-ai/sdk` package to interact with Claude models directly. Use `client.messages.create()` for single-turn and multi-turn conversations. Use `client.messages.stream()` for streaming with event-based consumption. `max_tokens` is always required. Content blocks are typed unions (`text`, `tool_use`, `thinking`). Use `client.messages.parse()` with `zodOutputFormat()` for structured outputs. Tool use requires a tool-result loop -- Claude returns `tool_use` blocks, you execute the tool and send back `tool_result` blocks. Extended thinking adds `thinking` content blocks before the response.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST always provide `max_tokens` in every `messages.create()` / `messages.stream()` call -- it is required and has no default)**

**(You MUST handle the `stop_reason` field to detect `end_turn`, `max_tokens`, `tool_use`, and `stop_sequence` -- ignoring it causes silent truncation or broken tool loops)**

**(You MUST iterate over `response.content` blocks (not assume a single text block) -- responses can contain `text`, `tool_use`, and `thinking` blocks mixed together)**

**(You MUST handle errors using `Anthropic.APIError` and its subclasses -- never use bare catch blocks without error type checking)**

**(You MUST never hardcode API keys -- always use environment variables via `process.env.ANTHROPIC_API_KEY`)**

</critical_requirements>

---

**Auto-detection:** Anthropic, @anthropic-ai/sdk, client.messages.create, client.messages.stream, client.messages.parse, client.messages.countTokens, client.messages.batches, ANTHROPIC_API_KEY, claude-sonnet, claude-opus, claude-haiku, ContentBlock, ToolUseBlock, tool_use, tool_result, thinking, budget_tokens, adaptive, cache_control, zodOutputFormat, betaZodTool, toolRunner

**When to use:**

• Building applications that call Claude models directly (Opus, Sonnet, Haiku families)
• Implementing streaming chat responses with event-based text accumulation
• Using tool use / function calling where Claude decides which tools to invoke
• Processing images, PDFs, or documents alongside text prompts
• Enabling extended thinking for complex reasoning tasks
• Extracting structured data from responses with Zod schema validation
• Caching large system prompts or conversation prefixes for cost savings
• Running batch jobs for high-volume, asynchronous processing
• Counting tokens before sending requests for cost estimation

**Key patterns covered:**

• Client initialization and configuration (retries, timeouts, API key)
• Messages API (`messages.create`, system prompts, multi-turn conversations)
• Streaming with `.stream()` helper and `stream: true` low-level SSE
• Tool use / function calling (tools array, `tool_use` / `tool_result` content blocks)
• Vision (base64 images, URL images, PDFs/documents)
• Extended thinking (`thinking` config, `budget_tokens`, thinking content blocks)
• Structured outputs (`zodOutputFormat`, `messages.parse`, `output_config`)
• Prompt caching (`cache_control: { type: "ephemeral" }`)
• Batch API (`messages.batches.create`)
• Token counting (`messages.countTokens`)
• Error handling, retries, and production best practices

**When NOT to use:**

• Multi-provider applications where you need to switch between multiple LLM providers -- use a unified provider SDK instead
• React-specific chat UI hooks (`useChat`, `useCompletion`) -- use a framework-integrated AI SDK
• When you need a higher-level agent framework -- consider the Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`)

---

Examples Index

• [Core: Setup & Configuration](examples/core.md) -- Client init, production config, error handling, token counting
• [Streaming](examples/streaming.md) -- `.stream()` helper, `stream: true` SSE, event types, abort
• [Tool Use / Function Calling](examples/tool-use.md) -- Tool definitions, tool loops, parallel tool calls, automated tool runner
• [Vision & Documents](examples/vision-documents.md) -- Base64 images, URL images, PDFs, multi-modal
• [Extended Thinking](examples/extended-thinking.md) -- Thinking config, streaming thinking, thinking with tool use
• [Quick API Reference](reference.md) -- Model IDs, method signatures, error types, streaming events, content block types

---

<philosophy>

Philosophy

The official Anthropic SDK provides **direct, typed access** to the Claude API. It is auto-generated from Anthropic's API specification using Stainless, giving you the exact API surface that Anthropic documents with full TypeScript types.

**Core principles:**

1. **Content blocks, not strings** -- Responses are arrays of typed content blocks (`TextBlock`, `ToolUseBlock`, `ThinkingBlock`), not plain strings. Always iterate over `response.content` and switch on `block.type`. 2. **Explicit resource limits** -- `max_tokens` is always required. There is no default. The API will reject requests without it. 3. **Tool use is a conversation loop** -- When `stop_reason === "tool_use"`, Claude is requesting you execute a tool. You must send the result back as a `tool_result` content block to continue the conversation. 4. **Built-in resilience** -- The SDK retries 2 times by default on 429, 409, 408, 529, and 5xx errors with exponential backoff. 5. **Streaming as a first-class pattern** -- Use `.stream()` for an event-based API with `.on("text", ...)`, or `stream: true` for raw SSE iteration.

**When to use the Anthropic SDK directly:**

• You only use Claude models and want the simplest, most direct integration
• You need access to Anthropic-specific features (extended thinking, prompt caching, batch API)
• You want minimal dependencies and zero abstraction over