Anthropic TypeScript SDK Guide (2026)

Complete reference for @anthropic-ai/sdk in TypeScript. Types, configuration, messages API, streaming, tool use, prompt caching, and error handling with full code examples.

The @anthropic-ai/sdk TypeScript package ships full type definitions for every API surface. This reference covers all major patterns with TypeScript-first examples.

Install & configure

npm install @anthropic-ai/sdk
# TypeScript 4.7+ required for correct generic inference

import Anthropic from "@anthropic-ai/sdk";

// Option 1: reads ANTHROPIC_API_KEY from process.env
const client = new Anthropic();

// Option 2: explicit key (never commit — use env vars or secrets manager)
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

// Option 3: custom base URL (useful for local proxies)
const client = new Anthropic({ baseURL: "https://your-proxy.example.com" });

Key TypeScript types

import type {
  Message,           // full response object
  MessageParam,      // { role, content } message
  ContentBlock,      // TextBlock | ToolUseBlock
  TextBlock,         // { type: "text"; text: string }
  ToolUseBlock,      // { type: "tool_use"; id; name; input }
  ToolResultBlock,   // { type: "tool_result"; tool_use_id; content }
  Tool,              // tool definition schema
  MessageStreamEvent // union of all SSE event types
} from "@anthropic-ai/sdk/resources/messages";

Type-safe message creation

import type { MessageCreateParamsNonStreaming } from "@anthropic-ai/sdk/resources/messages";

const params: MessageCreateParamsNonStreaming = {
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: "You are a helpful assistant.",
  messages: [
    { role: "user", content: "What is a TypeScript discriminated union?" }
  ]
};

const response: Message = await client.messages.create(params);

Multi-modal content (vision)

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 512,
  messages: [
    {
      role: "user",
      content: [
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: base64ImageData
          }
        },
        { type: "text", text: "Describe this diagram." }
      ]
    }
  ]
});

Typed tool use

import type { Tool } from "@anthropic-ai/sdk/resources/messages";

const weatherTool: Tool = {
  name: "get_weather",
  description: "Returns current conditions for a city.",
  input_schema: {
    type: "object" as const,
    properties: {
      city: { type: "string", description: "City name" },
      units: { type: "string", enum: ["celsius", "fahrenheit"] }
    },
    required: ["city"]
  }
};

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 512,
  tools: [weatherTool],
  messages: [{ role: "user", content: "Weather in Berlin?" }]
});

Prompt caching with types

import type { TextBlockParam } from "@anthropic-ai/sdk/resources/messages";

const systemBlock: TextBlockParam = {
  type: "text",
  text: largeStaticContext,
  cache_control: { type: "ephemeral" }
};

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 512,
  system: [systemBlock],
  messages: [{ role: "user", content: "Summarise this." }]
});

// Check cache performance
console.log("Cache read:", response.usage.cache_read_input_tokens);
console.log("Cache write:", response.usage.cache_creation_input_tokens);

Retry configuration

const client = new Anthropic({
  maxRetries: 3, // default is 2
  timeout: 60_000 // ms
});

Cost references

• Claude Cost Calculator — model your TypeScript app's monthly API bill
• Prompt-Pricing Recommender — choose Haiku vs Sonnet vs Opus for your use case

Frequently asked questions

Free tools

Related