api-ai-anthropic-sdk

What it does

Guides an AI agent to interact with Claude models using the official @anthropic-ai/sdk. It specifies how to initialize the client, how to call the Messages API for single-turn and multi-turn conversations, how to enable streaming, and how to handle tool use loops, vision blocks, extended thinking, and structured outputs. It also covers prompt caching, batch API usage, token counting, and production-ready error handling patterns.

How it works

• Client Setup: Initialize the Anthropic client, with optional production config (timeouts, maxRetries) and environment-based API key management.
• Messages API: Use client.messages.create() for interactions; always provide max_tokens; include system prompts and a list of user messages; iterate response.content blocks instead of assuming a single text block.
• Streaming: Use .stream() for event-based streaming, or stream: true with SSE, and accumulate text via streaming helpers; obtain finalMessage() when complete.
• Tool Use / Function Calling: Define tools with name, description, and input_schema; Claude may emit tool_use blocks; execute the tool and respond with tool_result blocks to continue.
• Vision & Documents: Send images or PDFs as content blocks alongside text within messages.
• Extended Thinking: Enable thinking blocks (adaptive or explicit budget tokens) and handle thinking blocks in the response content.
• Structured Outputs: Use zodOutputFormat and messages.parse with output_config to enforce typed, structured results.
• Prompt Caching: Use cache_control with ephemeral type to cache large prompts for cost savings; inspect usage tokens for cache read/write.
• Batch API: Supports messages.batches.create for high-volume processing.
• Token Counting: Access token counts via messages.countTokens.
• Error Handling: Catch Anthropic.APIError and related subclasses; not bare catch blocks; rethrow unexpected errors.

When to use it

• When building applications that call Claude models directly (Opus, Sonnet, Haiku families)
• When you need streaming chat responses with event-based accumulation
• When you require tool use / function calling with Claude decision points
• When processing images, PDFs, or documents alongside prompts
• When extended thinking is needed for complex reasoning
• When structured data extraction with type validation is desired
• When caching large system prompts can reduce costs
• When performing high-volume batch processing
• When estimating costs via token counting before requests

What it can touch

• Uses the official SDK commands and concepts: client, client.messages.create, client.messages.stream, client.messages.parse, zodOutputFormat, tool_use blocks, tool_result blocks, thinking blocks, and content blocks (TextBlock, ToolUseBlock, ThinkingBlock).
• Tools: tools array for tool definitions used in tool loops.
• Environment: ANTHROPIC_API_KEY via process.env.

Caveats

• All code must follow project conventions (kebab-case, named exports, import ordering, import type, named constants).
• max_tokens is mandatory for both messages.create() and messages.stream(); there is no default.
• stop_reason must be checked to handle tool_use and to continue the loop with tool_result.
• Iterate over response.content blocks; responses may include text, tool_use, and thinking blocks.
• Handle errors using Anthropic.APIError and its subclasses; avoid bare catch blocks.
• Do not hardcode API keys; rely on ANTHROPIC_API_KEY from environment variables.