Anthropic Agent SDK
(TypeScript)

What is the Anthropic Agent SDK?

The Anthropic Agent SDK (TypeScript) -- published as @anthropic-ai/claude-agent-sdk on npm -- is a library for building autonomous AI agents powered by Claude. It gives you the same tools, agent loop, and context management that power Claude Code, packaged as a library you can embed in your own applications.

Think of it this way: if the Anthropic SDK (@anthropic-ai/sdk) is a telephone that lets you talk to Claude, the Agent SDK is a complete robotic assistant -- Claude with hands. It can read files, run terminal commands, search the web, edit code, and orchestrate complex multi-step workflows without you implementing any of the tool execution logic.

Key Facts at a Glance

One-Sentence Summary

The Agent SDK wraps Claude's intelligence with built-in tool execution, turning a chat API into an autonomous agent that can read, write, search, and execute -- all with a single function call.

Technical Overview

The Agent SDK sits between your application and the Claude API, managing the entire agent lifecycle:

Two Primary Interfaces

1. query() -- A standalone function returning an async generator. Best for single-shot tasks and simple integrations.
2. V2 Session Interface (Preview) -- unstable_v2_createSession() provides a class-based session with explicit send() and stream() methods for multi-turn conversations.

Authentication

The SDK supports multiple authentication methods:

• Anthropic API Key -- ANTHROPIC_API_KEY environment variable
• Amazon Bedrock -- Set CLAUDE_CODE_USE_BEDROCK=1 with AWS credentials
• Google Vertex AI -- Set CLAUDE_CODE_USE_VERTEX=1 with GCP credentials
• Azure AI Foundry -- Set CLAUDE_CODE_USE_FOUNDRY=1 with Azure credentials

Architectural Position

The Agent SDK embodies several deliberate architectural choices:

1. Same Runtime as Claude Code -- The SDK spawns a Claude Code process under the hood. Your agent runs the same binary that powers the CLI.
2. Tool Execution, Not Tool Description -- Unlike the Client SDK, the Agent SDK executes tools directly. You define what Claude can do, not how.
3. Streaming-First -- The query() function returns an AsyncGenerator<SDKMessage, void>. Every interaction is streaming by default.
4. Security by Default -- Tools are not auto-approved. Explicit opt-in via allowedTools, permissionMode, or canUseTool.
5. Session Persistence -- Sessions persist to disk (JSONL format), enabling resume, fork, and inspection.

typescriptCopy
// Client SDK: You build the loop
let response = await client.messages.create({ ...params });
while (response.stop_reason === "tool_use") {
  const result = yourToolExecutor(response.tool_use);
  response = await client.messages.create({ tool_result: result, ...params });
}

// Agent SDK: The loop is built for you
for await (const message of query({ prompt: "Fix the bug in auth.py" })) {
  console.log(message);
}