Claude Agent SDK: Build Your First AI Agent in TypeScript (2026)

The Claude Agent SDK is Claude Code as a library. It gives your own Python or TypeScript program the same tools, agent loop and context management that power Claude Code, so an agent you build can read files, run commands, search the web and call your tools without you writing the loop yourself.

If you have used the plain Claude API, the difference is who does the work. With the API you send a message, get a reply, and write the logic that decides which tool to call next. With the Agent SDK you give it a task and a set of allowed tools, and it plans, acts, checks the result and keeps going until the task is done.

Agent SDK, Client SDK, Claude Code or Managed Agents?

Anthropic offers four ways to build with Claude, and picking the right one saves a rewrite:

Use the Agent SDK when the job looks like what Claude Code does (multi-step work with files, commands and tools) but needs to run inside your product, a backend job or CI.

Install the Claude Agent SDK

You need Node.js 18+ or Python 3.10+ and an API key from the Claude Console.

TypeScript, in a new project:

npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

Python:

pip install claude-agent-sdk

Both packages bundle a native Claude Code binary, so most installs need nothing else. Set your key in the shell that runs the agent:

export ANTHROPIC_API_KEY=your-api-key

The SDK reads the key from the environment and does not load .env files on its own, so load them yourself (with dotenv, for example) if that is where your key lives. No key yet? Here is how to get a Claude API key.

Your first agent

This agent reviews a file for bugs and fixes them. The whole program is one query() call and a loop over the messages it streams back:

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

for await (const message of query({
  prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
  },
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
      else if ("name" in block) console.log(`Tool: ${block.name}`);
    }
  } else if (message.type === "result") {
    console.log(`Done: ${message.subtype}`);
  }
}

Run it with npx tsx agent.ts. The agent reads the file, works out which inputs would crash it, edits the code to handle them and reports Done: success. You never told it which tool to call when. That is the point.

The three parts:

• query starts the agent loop and returns an async iterator of messages: reasoning, tool calls, tool results and the final result.
• prompt is the task, in plain language.
• options sets what the agent may do. allowedTools pre-approves tools, and permissionMode: "acceptEdits" lets it change files without asking.

The Python version is the same shape:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        print(message)

asyncio.run(main())

Choosing tools and permissions

The tools you allow decide what kind of agent you have:

Add WebSearch for research tasks, and set systemPrompt to give the agent a role and rules. Start with the narrowest set that does the job and widen it only when you need to. An agent that can run Bash can do anything your user account can.

What else the Claude Agent SDK includes

Everything that makes Claude Code useful carries over:

• Hooks to run your own code before or after tool calls, for logging, validation or blocking risky actions
• Subagents for focused subtasks running in parallel
• MCP servers to connect databases, APIs and your own product (see what an MCP server is)
• Sessions to keep context across turns and resume later
• Skills, commands and memory loaded from your project's .claude/ folder, the same as Claude Code

Two rules before you ship it

1. Use API keys, not claude.ai logins. Unless Anthropic has approved it, third-party products built on the Agent SDK may not offer claude.ai login or claude.ai rate limits to their users. Authenticate with an API key (or Bedrock, Vertex or Foundry credentials).
2. Keep your own brand. You can say an agent is "Powered by Claude", but your product must not present itself as Claude Code.

When I reach for the Agent SDK

In my own products I use the plain Claude API when the flow is fixed and I want full control, such as a chat reply or a structured extraction. I reach for an agent loop when the number of steps is unknown up front: research that branches, multi-step jobs over files, or a task that needs to check its own work. ServeStack Studio, for example, is a pipeline of cooperating agents that goes from trend research to a script, a storyboard and a generated video ad.

Frequently asked questions

Is the Claude Agent SDK free? The SDK is free to install. The model calls it makes are billed to your Anthropic API account, or to Bedrock, Vertex or Foundry if you use those.

Is it the same as the Claude Code SDK? It is the successor. Anthropic publishes a migration guide from the older Claude Code SDK packages to the Agent SDK.

Can I use it from another language? The SDK is Python and TypeScript. From other languages you can run the Claude Code CLI as a subprocess with -p and --output-format json.

Does it need Claude Code installed? Usually not. Both SDKs bundle the Claude Code binary.

---

Building an agent into a real product means permissions, cost limits, evaluation and a UI people trust. If you want help with that, see my AI integration services.