Claude Agent SDK
Build applications that run the Claude Code agent loop programmatically: agents that read files,
write code, run commands, search the web, and delegate to subagents from inside your own program.
Key distinction: the Agent SDK (claude-agent-sdk) runs the full agent loop with built-in
tools. The Anthropic Client SDK (anthropic) makes raw API calls. Use the Agent SDK when you want
an autonomous tool-using agent, not a chat completion.
|
TypeScript |
Python |
| Package |
@anthropic-ai/claude-agent-sdk |
claude-agent-sdk |
| Install |
npm install @anthropic-ai/claude-agent-sdk |
pip install claude-agent-sdk |
| Auth |
ANTHROPIC_API_KEY env var |
ANTHROPIC_API_KEY env var |
| Entry point |
query() |
query() |
| Source |
anthropics/claude-agent-sdk-typescript |
anthropics/claude-agent-sdk-python |
The CLI package @anthropic-ai/claude-code ships inside the SDK. No separate install.
Source of truth
This SDK changes faster than any bundled document. Option shapes, tool names, defaults, and whole
features move between releases: fork_session changed type, plugins changed from paths to config
objects, and the TypeScript V2 preview was removed outright. Treat this skill's knowledge as
orientation, never as the authority.
Three tiers. Stop at the first one that answers the question:
- The project's installed SDK. TypeScript: the type definitions under
node_modules/@anthropic-ai/claude-agent-sdk/ and the version in its package.json. Python:
the installed package under site-packages/claude_agent_sdk/, or inspect.signature() on the
symbol. This tier wins over everything else, because it is what the user's code will run
against.
- Current official documentation, https://code.claude.com/docs/en/agent-sdk/. Use it when
nothing is installed yet, or when the question is about behavior rather than a signature.
- The references in this skill. Worked examples and orientation. Never the last word on a
signature, an option shape, a default, or whether a feature still exists.
Classify a claim before you rely on it:
| Class |
Example |
Resolve with |
| STABLE |
"Restrict allowedTools to what the task needs." |
This skill |
| API-SENSITIVE |
"forkSession is a boolean used with resume." |
Tier 1, then tier 2 |
| MODEL-SENSITIVE |
"This model id and effort level exist." |
Tier 2 |
Never emit API-sensitive code from memory when tier 1 or tier 2 can settle it. Items marked
(verify) in the references are the ones that failed tier-2 resolution at the last refresh: they
are unconfirmed rather than confirmed-absent, and checking them is cheap.
Step 1: Detect the environment
Do this before writing a line of code, and state what you found.
- Language. A
package.json naming @anthropic-ai/claude-agent-sdk means TypeScript. A
pyproject.toml, requirements.txt, or uv.lock naming claude-agent-sdk means Python.
- Installed version.
npm ls @anthropic-ai/claude-agent-sdk or pip show claude-agent-sdk.
Record it: every API-sensitive answer you give is relative to that version.
- Nothing installed. Say so, install the current release, and resolve signatures from tier 2.
- Version pinned below current. Honor the pin. Resolve against the installed types, and if the
user asks for a feature that release does not have, say which version added it instead of
emitting code that cannot run.
Step 2: Pick the shape
| Need |
Shape |
Reference |
| One task, run to completion |
query() |
references/sdk-api.md |
| Multi-turn with retained context |
ClaudeSDKClient (Python), or query() with resume |
references/sessions-subagents.md |
| Branch a conversation without mutating it |
resume plus forkSession |
references/sessions-subagents.md |
| Delegate specialized work |
agents plus the Agent tool |
references/sessions-subagents.md |
| Give the agent your own functions |
in-process MCP server |
references/mcp-plugins-skills.md |
| Reuse existing Claude Code plugins |
plugins and settingSources |
references/mcp-plugins-skills.md |
| A machine-readable result |
outputFormat with a JSON schema |
references/sdk-api.md |
| Coarse "what may it use at all" |
allowedTools / disallowedTools / permissionMode |
references/permissions-hooks-security.md |
| A rule that must hold on every call |
PreToolUse hook |
references/permissions-hooks-security.md |
| Decide unresolved requests in code |
canUseTool |
references/permissions-hooks-security.md |
| Run untrusted work |
sandbox and container isolation |
references/deployment.md |
| Ship it somewhere |
ephemeral or long-running hosting |
references/deployment.md |
Load only the reference the chosen row names. Loading all five defeats the point.
Step 3: Security model
Three mechanisms, three jobs. Substituting one for another is the most common way an SDK
application ends up with security that does not run:
| Mechanism |
Job |
allowedTools / disallowedTools / permissionMode |
Coarse policy: what the agent may use at all |
PreToolUse hook |
Always-on enforcement: runs for every matching call, before permission resolution |
canUseTool |
Interactive fallback: runs only for calls no rule, mode, or hook already resolved |
A validation rule that must always hold belongs in a PreToolUse hook. Anything you allow-list
never reaches canUseTool, so a check placed there stops running the moment the tool is approved,
silently. disallowedTools is the only hard block and outranks even bypassPermissions. Details
and worked examples: references/permissions-hooks-security.md.
Also standing: set maxTurns and maxBudgetUsd on anything autonomous, keep secrets out of
prompts (use env or an MCP tool instead), and isolate untrusted work in a container.
Step 4: Build and validate
- Write the smallest program that does the job. Resist adding options you have not verified.
- Resolve every API-sensitive detail against tier 1, then tier 2.
- Type-check where the project supports it (
tsc --noEmit, or the project's type checker).
- Run it once on a cheap prompt with
maxTurns and maxBudgetUsd set low, before running it for
real.
- Report which facts came from the installed SDK, which from the documentation, and name anything
you could not verify. A named gap is useful; a confident guess is not.
References
| File |
Holds |
references/sdk-api.md |
Install, query(), full options table, built-in tools, streaming, structured output, cost tracking, migration from claude-code-sdk |
references/sessions-subagents.md |
Sessions, resume, fork, session metadata, introspection, subagent definitions, Python client methods |
references/permissions-hooks-security.md |
Permission modes and evaluation order, canUseTool, hook events and matchers, security practices |
references/mcp-plugins-skills.md |
Custom tools as in-process MCP servers, external MCP servers, loading plugins and settings |
references/deployment.md |
Hosting shapes, sandbox isolation, CI/CD review agent, research pipeline, chat loop |
references/reasoning-patterns.md in this directory belongs to the prompt-engineer agent, not to
the SDK. It sits here because the VS Code export mirrors plugin-root references into the consuming
skill directory.
Official documentation
1---2name: agent-sdk-builder3description: Run the Claude Agent SDK (formerly Claude Code SDK) loop inside your own program, not the `anthropic` client SDK for chat completions. TRIGGER WHEN: code references claude-agent-sdk, user says "agent sdk", "build an agent", "programmatic claude", "claude code sdk", "sidecar", "run claude programmatically"; or asks about tool integration, subagent orchestration, prompt caching or model migration inside that loop.4---56# Claude Agent SDK78Build applications that run the Claude Code agent loop programmatically: agents that read files,9write code, run commands, search the web, and delegate to subagents from inside your own program.1011**Key distinction**: the Agent SDK (`claude-agent-sdk`) runs the full agent loop with built-in12tools. The Anthropic Client SDK (`anthropic`) makes raw API calls. Use the Agent SDK when you want13an autonomous tool-using agent, not a chat completion.1415| | TypeScript | Python |16|---|---|---|17| **Package** | `@anthropic-ai/claude-agent-sdk` | `claude-agent-sdk` |18| **Install** | `npm install @anthropic-ai/claude-agent-sdk` | `pip install claude-agent-sdk` |19| **Auth** | `ANTHROPIC_API_KEY` env var | `ANTHROPIC_API_KEY` env var |20| **Entry point** | `query()` | `query()` |21| **Source** | `anthropics/claude-agent-sdk-typescript` | `anthropics/claude-agent-sdk-python` |2223The CLI package `@anthropic-ai/claude-code` ships inside the SDK. No separate install.2425---2627## Source of truth2829This SDK changes faster than any bundled document. Option shapes, tool names, defaults, and whole30features move between releases: `fork_session` changed type, `plugins` changed from paths to config31objects, and the TypeScript V2 preview was removed outright. Treat this skill's knowledge as32orientation, never as the authority.3334Three tiers. Stop at the first one that answers the question:35361. **The project's installed SDK.** TypeScript: the type definitions under37 `node_modules/@anthropic-ai/claude-agent-sdk/` and the version in its `package.json`. Python:38 the installed package under `site-packages/claude_agent_sdk/`, or `inspect.signature()` on the39 symbol. This tier wins over everything else, because it is what the user's code will run40 against.412. **Current official documentation**, https://code.claude.com/docs/en/agent-sdk/. Use it when42 nothing is installed yet, or when the question is about behavior rather than a signature.433. **The references in this skill.** Worked examples and orientation. Never the last word on a44 signature, an option shape, a default, or whether a feature still exists.4546Classify a claim before you rely on it:4748| Class | Example | Resolve with |49|---|---|---|50| STABLE | "Restrict `allowedTools` to what the task needs." | This skill |51| API-SENSITIVE | "`forkSession` is a boolean used with `resume`." | Tier 1, then tier 2 |52| MODEL-SENSITIVE | "This model id and effort level exist." | Tier 2 |5354Never emit API-sensitive code from memory when tier 1 or tier 2 can settle it. Items marked55*(verify)* in the references are the ones that failed tier-2 resolution at the last refresh: they56are unconfirmed rather than confirmed-absent, and checking them is cheap.5758---5960## Step 1: Detect the environment6162Do this before writing a line of code, and state what you found.6364- **Language.** A `package.json` naming `@anthropic-ai/claude-agent-sdk` means TypeScript. A65 `pyproject.toml`, `requirements.txt`, or `uv.lock` naming `claude-agent-sdk` means Python.66- **Installed version.** `npm ls @anthropic-ai/claude-agent-sdk` or `pip show claude-agent-sdk`.67 Record it: every API-sensitive answer you give is relative to that version.68- **Nothing installed.** Say so, install the current release, and resolve signatures from tier 2.69- **Version pinned below current.** Honor the pin. Resolve against the installed types, and if the70 user asks for a feature that release does not have, say which version added it instead of71 emitting code that cannot run.7273## Step 2: Pick the shape7475| Need | Shape | Reference |76|---|---|---|77| One task, run to completion | `query()` | `references/sdk-api.md` |78| Multi-turn with retained context | `ClaudeSDKClient` (Python), or `query()` with `resume` | `references/sessions-subagents.md` |79| Branch a conversation without mutating it | `resume` plus `forkSession` | `references/sessions-subagents.md` |80| Delegate specialized work | `agents` plus the `Agent` tool | `references/sessions-subagents.md` |81| Give the agent your own functions | in-process MCP server | `references/mcp-plugins-skills.md` |82| Reuse existing Claude Code plugins | `plugins` and `settingSources` | `references/mcp-plugins-skills.md` |83| A machine-readable result | `outputFormat` with a JSON schema | `references/sdk-api.md` |84| Coarse "what may it use at all" | `allowedTools` / `disallowedTools` / `permissionMode` | `references/permissions-hooks-security.md` |85| A rule that must hold on every call | `PreToolUse` hook | `references/permissions-hooks-security.md` |86| Decide unresolved requests in code | `canUseTool` | `references/permissions-hooks-security.md` |87| Run untrusted work | sandbox and container isolation | `references/deployment.md` |88| Ship it somewhere | ephemeral or long-running hosting | `references/deployment.md` |8990Load only the reference the chosen row names. Loading all five defeats the point.9192## Step 3: Security model9394Three mechanisms, three jobs. Substituting one for another is the most common way an SDK95application ends up with security that does not run:9697| Mechanism | Job |98|---|---|99| `allowedTools` / `disallowedTools` / `permissionMode` | Coarse policy: what the agent may use at all |100| `PreToolUse` hook | Always-on enforcement: runs for every matching call, before permission resolution |101| `canUseTool` | Interactive fallback: runs only for calls no rule, mode, or hook already resolved |102103**A validation rule that must always hold belongs in a `PreToolUse` hook.** Anything you allow-list104never reaches `canUseTool`, so a check placed there stops running the moment the tool is approved,105silently. `disallowedTools` is the only hard block and outranks even `bypassPermissions`. Details106and worked examples: `references/permissions-hooks-security.md`.107108Also standing: set `maxTurns` and `maxBudgetUsd` on anything autonomous, keep secrets out of109prompts (use `env` or an MCP tool instead), and isolate untrusted work in a container.110111## Step 4: Build and validate1121131. Write the smallest program that does the job. Resist adding options you have not verified.1142. Resolve every API-sensitive detail against tier 1, then tier 2.1153. Type-check where the project supports it (`tsc --noEmit`, or the project's type checker).1164. Run it once on a cheap prompt with `maxTurns` and `maxBudgetUsd` set low, before running it for117 real.1185. Report which facts came from the installed SDK, which from the documentation, and name anything119 you could not verify. A named gap is useful; a confident guess is not.120121---122123## References124125| File | Holds |126|---|---|127| `references/sdk-api.md` | Install, `query()`, full options table, built-in tools, streaming, structured output, cost tracking, migration from `claude-code-sdk` |128| `references/sessions-subagents.md` | Sessions, resume, fork, session metadata, introspection, subagent definitions, Python client methods |129| `references/permissions-hooks-security.md` | Permission modes and evaluation order, `canUseTool`, hook events and matchers, security practices |130| `references/mcp-plugins-skills.md` | Custom tools as in-process MCP servers, external MCP servers, loading plugins and settings |131| `references/deployment.md` | Hosting shapes, sandbox isolation, CI/CD review agent, research pipeline, chat loop |132133`references/reasoning-patterns.md` in this directory belongs to the `prompt-engineer` agent, not to134the SDK. It sits here because the VS Code export mirrors plugin-root references into the consuming135skill directory.136137## Official documentation138139- [Overview](https://code.claude.com/docs/en/agent-sdk/overview)140- [TypeScript reference](https://code.claude.com/docs/en/agent-sdk/typescript)141- [Python reference](https://code.claude.com/docs/en/agent-sdk/python)142- [Permissions](https://code.claude.com/docs/en/agent-sdk/permissions)143- [Hooks](https://code.claude.com/docs/en/agent-sdk/hooks)144- [Sessions](https://code.claude.com/docs/en/agent-sdk/sessions)145- [Subagents](https://code.claude.com/docs/en/agent-sdk/subagents)146- [Custom tools and MCP](https://code.claude.com/docs/en/agent-sdk/custom-tools)147- [Hosting](https://code.claude.com/docs/en/agent-sdk/hosting)148- [Secure deployment](https://code.claude.com/docs/en/agent-sdk/secure-deployment)149- [Migration guide](https://code.claude.com/docs/en/agent-sdk/migration-guide)150- [Demo apps](https://github.com/anthropics/claude-agent-sdk-demos)
acaprino