agent-sdk-quickstart

Claude Agent SDK — Quickstart

The Claude Agent SDK is Anthropic's framework for building agents. It handles the tool-use loop, context compaction, sub-agent spawning, and MCP integration so you don't reinvent them.

When to Use

• Starting a new agent project
• Migrating from hand-rolled messages.create loops
• Need sub-agent orchestration, compaction, or skills out-of-box
• Building CLI tools, automation, or backend agents

SDK vs Direct API vs Managed Agents

Approach	Best for	Tradeoff
Direct messages.create	Simple one-shot calls	You manage everything
Agent SDK (client-side)	Custom agents with full control	You run the loop, manage state
Managed Agents API (/v1/agents)	Production agents at scale	Anthropic runs the loop server-side

Use the SDK when you need more control than Managed Agents but don't want to rewrite the tool loop.

Install

TypeScript:

npm i @anthropic-ai/claude-agent-sdk

Python:

pip install claude-agent-sdk

Minimal Agent — TypeScript

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "What files are in the current directory?",
  options: {
    model: "claude-sonnet-4-6",
    permissionMode: "default",
  },
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "text") process.stdout.write(block.text);
    }
  }
}

Under the hood: the SDK connects to Claude, provides default tools (file read, bash, web fetch), runs the tool-use loop, and streams results back.

Minimal Agent — Python

import asyncio
from claude_agent_sdk import query

async def main():
    async for msg in query(
        prompt="What files are here?",
        options={"model": "claude-sonnet-4-6"},
    ):
        if msg.type == "assistant":
            for block in msg.message.content:
                if block.type == "text":
                    print(block.text, end="")

asyncio.run(main())