Claude Agent SDK: How to Build Agents (2026)

TL;DR

• The Claude Agent SDK is Anthropic's library for building AI agents in your own code — the same agent engine that powers Claude Code, exposed as claude-agent-sdk for Python (3.10+) and @anthropic-ai/claude-agent-sdk for TypeScript.
• It was renamed from `claude-code-sdk` in late 2025; if a tutorial says ClaudeCodeOptions, it's outdated — the class is now ClaudeAgentOptions.
• You get the full agent loop for free: file tools, Bash, web search, custom tools via @tool, MCP servers (that's how you wire in Jira or Shopify), subagents, hooks, and permissions. You pay only for Claude API tokens.
• It talks to the Anthropic Messages API, so you can point it at a gateway with ANTHROPIC_BASE_URL — we tested it against [Velokey](https://api.velokey.ai)'s /v1/messages endpoint and it runs on one key with credit billing.

Everyone's building agents right now, and most guides stop at the ten-line quickstart. This one covers what happens after: how to install it without the common Node trap, how to wire in real tools like Jira and Shopify, what it actually costs to run, and how to route it through a gateway. Let's get into it.

What is the Claude Agent SDK?

The Claude Agent SDK is a library that gives your own application the same autonomous agent loop that runs inside Claude Code — reading and writing files, running commands, searching the web, and calling tools, without you hand-writing the tool-call loop. Anthropic ships it for Python and TypeScript, and per the official docs it's the supported way to build production agents on Claude.

The important context most people miss: it used to be called the Claude Code SDK. Anthropic renamed it to the Claude Agent SDK in late 2025 to signal it's for building *any* agent, not just coding tools. The package, the imports, and one core class all changed — claude-code-sdk became claude-agent-sdk, and ClaudeCodeOptions became ClaudeAgentOptions. A lot of blog posts and Stack Overflow answers still reference the old names, so if your import fails, that's usually why.

Under the hood, the SDK wraps the Claude Code CLI as a subprocess. Your Python or TypeScript code talks to the SDK; the SDK drives the bundled CLI; the CLI talks to Claude. That architecture matters for two reasons we'll come back to: the CLI is a Node binary (so you need Node installed even for the Python SDK), and the CLI does aggressive prompt caching on its system prompt (which changes your cost math).

How do I install and use the Claude Agent SDK?

Install the Claude Agent SDK from PyPI (or npm), set your API key, and call query() — a working agent is about ten lines. Python needs 3.10 or newer:

pip install claude-agent-sdk
export ANTHROPIC_API_KEY="sk-ant-..."

Here's the minimal one-shot agent. query() returns an async iterator of messages:

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="List the Python files in this repo and summarize each."):
        print(message)

anyio.run(main)

For anything interactive or multi-turn, use ClaudeSDKClient and configure it with ClaudeAgentOptions:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt="You are a careful code-review assistant.",
    allowed_tools=["Read", "Grep", "Glob"],
    permission_mode="acceptEdits",
    max_turns=10,
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Review auth.py for security issues.")
    async for msg in client.receive_response():
        print(msg)

Two install gotchas that trip people up, neither of which is in the ten-line quickstart:

What can you build with the Claude Agent SDK?

You can build any agent that needs file access, command execution, or tool use — from a code reviewer to a customer-support triager to a data-pipeline operator. The SDK hands you five building blocks, and the whole design is about controlling what the agent is allowed to do:

Custom tools are the cleanest part. Decorate a function and the agent can call it directly — no separate process, no network hop:

from claude_agent_sdk import tool

@tool("get_order", "Look up an order by ID", {"order_id": str})
async def get_order(args):
    order = db.fetch(args["order_id"])
    return {"content": [{"type": "text", "text": str(order)}]}

Hooks and permissions are what turn a demo into something you'd run unattended. A PreToolUse hook can block a Bash command that matches a dangerous pattern; permission_mode decides whether the agent pauses for approval or auto-accepts edits. In production, most teams start with a tight allowed_tools list and open it up as they trust the agent — the opposite of the wide-open quickstart.

The sixth block, and the one people reach for once a single agent gets slow, is subagents. The SDK can spawn a fresh sub-agent with its own context to handle a scoped subtask, then hand the result back — Claude Code uses this to fan out across files. It's the built-in answer to "can it work on several things in parallel" and "how do I keep the main context from filling up": delegate the noisy work (reading ten files, running a test matrix) to subagents so the main agent stays focused. Session forking is the related trick for branching an in-progress conversation.

How do I integrate Jira or Shopify with the Claude Agent SDK?

You integrate Jira, Shopify, or any external system by adding its MCP server to mcp_servers in ClaudeAgentOptions — the SDK doesn't have Jira-specific code, it speaks the open Model Context Protocol, and both Atlassian and Shopify ship MCP servers. This is the answer to the most-asked integration questions ("how to connect Jira/Shopify with Claude Agent SDK"): there's no special connector, you register an MCP server and allow its tools.

The pattern is the same for both. Point the SDK at the MCP server (a local command or a remote URL), then allow the tools it exposes:

options = ClaudeAgentOptions(
    mcp_servers={
        "jira": {
            "command": "npx",
            "args": ["-y", "@atlassian/mcp-server-jira"],
            "env": {"JIRA_API_TOKEN": os.environ["JIRA_API_TOKEN"]},
        }
    },
    allowed_tools=["mcp__jira__search_issues", "mcp__jira__create_issue"],
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Find open bugs assigned to me and summarize them.")
    async for msg in client.receive_response():
        print(msg)

Swap the server block for @shopify/mcp-server (with your Shopify token) and the same agent can read orders or update products. Two things to get right: the tool names follow the mcp__<server>__<tool> convention, so your allowed_tools entries must match exactly, and each MCP server needs its own credential in env. If the agent says a tool isn't available, it's almost always a name mismatch or a missing token, not an SDK bug.

If the vendor hosts a remote MCP server instead of a local command, register it by URL rather than command/args — {"jira": {"url": "https://mcp.atlassian.com/v1/sse"}} — and the SDK connects over the network. Local (stdio) servers are simpler for development and keep the token on your machine; remote (URL) servers save you from installing anything. Either way, the allowed_tools and per-server credential rules are the same.

How do I run the Claude Agent SDK through a gateway?

Set ANTHROPIC_BASE_URL to your gateway's root, and the SDK sends every request there instead of api.anthropic.com — no code change. The SDK honors the standard Anthropic environment variables, so any backend that exposes the Anthropic Messages API (/v1/messages) works: a corporate proxy, a regional bridge, or a unified gateway.

We tested this against [Velokey](https://api.velokey.ai), which exposes an Anthropic-compatible /v1/messages endpoint. A live request to it returned a standard Messages response (stop_reason: end_turn, Anthropic-shaped usage), which is exactly what the SDK expects:

export ANTHROPIC_BASE_URL="https://api.velokey.ai"
export ANTHROPIC_API_KEY="sk-your-velokey-key"
# then run your agent as usual — set the model to one Velokey serves:

options = ClaudeAgentOptions(
    model="claude-sonnet-5",      # or claude-opus-4-8
    allowed_tools=["Read", "Grep"],
    max_turns=8,
)

Why route an agent through a gateway at all? One key instead of a separate Anthropic account, tier, and 30-day-retention setup; credit-based billing you can cap; and the same key reaches [Claude Opus 4.8](/model/claude-opus-4-8), [Claude Sonnet 5](/model/claude-sonnet-5), and other models you might use elsewhere. If your proxy wants a bearer token instead of the x-api-key header, set ANTHROPIC_AUTH_TOKEN rather than ANTHROPIC_API_KEY. It's the same drop-in idea as pointing an OpenAI-compatible tool at a gateway — see our Qwen CLI guide for the OpenAI-format equivalent.

How much does the Claude Agent SDK cost?

The SDK itself is free and open-source — you pay for the Claude API tokens the agent consumes, and agents consume a lot of them. Every turn re-sends the growing conversation, every tool result comes back into context, and a single "fix this bug" task can run ten-plus turns. That's the cost surprise: the code is ten lines, but the token bill scales with how much the agent explores.

Three levers keep it in check, and the SDK builds in the biggest one for you:

That last row is real, not theoretical: in our test request the response reported tens of thousands of cache_read_input_tokens, meaning the large system prompt was served from cache at roughly a tenth of the input price rather than re-billed every turn. It's the main reason agent costs aren't as brutal as the turn count suggests. For the full per-model token math, see our Claude API pricing guide; if you want a working single call to a Claude model before you wire up an agent, how to call Claude with an API key covers the basics.

Frequently Asked Questions

What is the Claude Agent SDK?

It's Anthropic's official library for building AI agents in Python or TypeScript, using the same autonomous agent loop that powers Claude Code. It handles the tool-call loop, file operations, command execution, and MCP integrations for you, so you write the goal and the tools, not the orchestration. You pay only for Claude API tokens.

Is the Claude Agent SDK the same as the Claude Code SDK?

Yes — it's the renamed version. Anthropic renamed claude-code-sdk to claude-agent-sdk in late 2025, and ClaudeCodeOptions became ClaudeAgentOptions. The functionality carried over; only the package and class names changed. If a tutorial imports the old names, it predates the rename and the imports will fail on the current package.

How do I install the Claude Agent SDK?

Run pip install claude-agent-sdk (Python 3.10+) or npm install @anthropic-ai/claude-agent-sdk for TypeScript, then set ANTHROPIC_API_KEY. Because the SDK drives the bundled Claude Code CLI as a subprocess, you also need Node.js installed, even for the Python package — a missing Node is the most common install failure.

How do I connect Jira or Shopify to a Claude Agent SDK agent?

Add the vendor's MCP server to mcp_servers in ClaudeAgentOptions and allow its tools. Both Atlassian (Jira) and Shopify publish MCP servers, so there's no custom connector to write — you register the server with its API token and list its tools (named mcp__<server>__<tool>) in allowed_tools.

Does the Claude Agent SDK work with a gateway or proxy?

Yes. It honors the ANTHROPIC_BASE_URL environment variable, so it routes to any backend that exposes the Anthropic Messages API (/v1/messages) with no code change. We verified a live request against Velokey's Anthropic-compatible endpoint. Use ANTHROPIC_API_KEY for x-api-key proxies or ANTHROPIC_AUTH_TOKEN for bearer-token ones.

Which models does the Claude Agent SDK use?

It uses Claude models through whatever endpoint you point it at — by default Anthropic's latest, and you can set a specific one via the model option (for example claude-sonnet-5 or claude-opus-4-8). Through a gateway, you can select any Claude model that gateway serves, which is handy for using a cheaper model on routine agent runs.

Is the Claude Agent SDK free?

The SDK is free and open-source, but running an agent costs Claude API tokens, and multi-turn agent loops use them quickly. Control spend by choosing a cheaper model for routine work, setting max_turns, and limiting tool access — and rely on the built-in prompt caching, which serves the repeated system prompt at roughly a tenth of the input price.