The rename
Anthropic renamed the Claude Code SDK to the Claude Agent SDK to reflect that it builds agents for more than coding. The packages changed with it:
| Old | New | |
|---|---|---|
| Python | claude-code-sdk |
claude-agent-sdk |
| TypeScript / JavaScript | @anthropic-ai/claude-code |
@anthropic-ai/claude-agent-sdk |
| Python options class | ClaudeCodeOptions |
ClaudeAgentOptions |
One breaking change matters most when migrating: the SDK no longer uses Claude Code’s system prompt by default. To get the old behavior, set systemPrompt to { type: "preset", preset: "claude_code" }.
What you get
The SDK runs the Claude Code binary as a library, so the agent can do what Claude Code does:
- Built-in tools: read, write and edit files, run commands, search the web.
- The agent loop: Claude plans, calls tools, reads the results and decides the next step. The SDK handles orchestration, tool execution, context management and retries; you consume a stream of messages.
- Permissions: which tools run without approval, which need it.
- Hooks, subagents, MCP servers and plugins, the same building blocks as in the CLI.
- Sessions you can resume or fork.
- Skills, commands and memory loaded from
.claude/and~/.claude/, as in Claude Code.
A first agent in four steps
- Requirements. Node.js 18.14+ or Python 3.10+, and an API key from the Claude Console.
- Install.
pip install claude-agent-sdkornpm install @anthropic-ai/claude-agent-sdk. - Set the key.
export ANTHROPIC_API_KEY=.... The SDK does not load.envfiles itself. For Bedrock, Google Cloud or Foundry, setCLAUDE_CODE_USE_BEDROCK=1,CLAUDE_CODE_USE_VERTEX=1orCLAUDE_CODE_USE_FOUNDRY=1with that provider’s credentials. - Call
query. Shortened from the quickstart:
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())
allowed_tools pre-approves those tools. To limit which built-in tools exist at all, pass them as tools instead; with allowed_tools, the agent can still call others, subject to the permission mode.
SDK, CLI with -p, or something else
| You want to | Use |
|---|---|
| Work interactively or run a one-off task from a terminal | Claude Code CLI |
| Script Claude Code in CI, a git hook or a shell loop, in any language | claude -p with --output-format json |
| Embed the agent in your own Python or TypeScript app, with callbacks for tool approval and typed message objects | Agent SDK |
| Call the model directly and write the tool loop yourself | Client SDK (the Claude API) |
| Let Anthropic host the agent and its sandbox | Managed Agents |
Anthropic’s own docs describe claude -p as “the Agent SDK via the CLI”. The difference is control: the packages give you structured outputs, tool approval callbacks and native message objects. For scripted runs, the docs recommend --bare, which skips local hooks, skills, plugins, MCP servers and CLAUDE.md so a run behaves the same on every machine.
The misunderstanding: “the SDK is a thin wrapper around the API”
The Client SDK is that. The Agent SDK is Claude Code itself, packaged: it executes tools directly instead of asking your code to implement them, and by default it picks up the same settings and CLAUDE.md files the CLI would find on that machine. That is convenient on a laptop and a surprise on a server, where a stray ~/.claude can change behavior. Pass an empty settingSources when you deploy.
What this means for a team
An agent built on the SDK has the same memory model as Claude Code: what is in the working directory, CLAUDE.md, and the session. Two agents built by two developers do not share what either learned, and an agent running for customers should usually not read a developer’s personal settings at all. See Claude Code memory, plugins and memory, and shared memory across coding agents.
Where Bombos fits
When a team builds its own agents on the SDK, each one starts with only the context someone passes in. Bombos is a plugin that gives those agents, Claude Code and the team’s other AI tools one shared memory: team knowledge, rules the team learned, and what already lives in mail, documents and repos, traceable to its source, in the cloud or on your own server. One developer can try it on their own agents first.
Related questions
Can I use my Claude Pro or Max login with the Agent SDK?
For your own use, the SDK authenticates with an API key from the Claude Console or with Bedrock, Google Cloud's Agent Platform or Microsoft Foundry credentials. Anthropic does not allow third-party developers to offer claude.ai login or rate limits in products built on the SDK unless previously approved.
Do I have to install Claude Code separately?
Usually not. Both the Python and TypeScript packages bundle a native Claude Code binary. Exceptions are a Python source install, for example on ARM64 Windows, and npm installs that skip optional dependencies.
Does the SDK read CLAUDE.md and .claude/settings.json?
Yes, by default. Leaving out settingSources loads user, project and local settings, CLAUDE.md files and custom commands, like the CLI. Pass an empty list to run isolated, which the docs recommend for CI, deployed apps and multi-tenant systems.
What changed in the rename besides the name?
The packages moved to claude-agent-sdk and @anthropic-ai/claude-agent-sdk, ClaudeCodeOptions became ClaudeAgentOptions in Python, and the SDK no longer uses Claude Code's system prompt by default. Ask for it with systemPrompt set to the claude_code preset.
Can I call my agent Claude Code?
No. Anthropic's branding guidelines allow names like Claude Agent or YourAgent Powered by Claude, and do not permit Claude Code or Claude Code Agent, or visuals that mimic Claude Code.
