Menú
Use when building custom AI agents headlessly, embedding Claude Code tools in an app, or running scripted/cron agents—need SDK package names, setup, core API entry points, supported languages, and relation to Claude Code CLI and Messages...
Basado en la clasificación ocupacional SOC
Use when unsure which Claude Code capability fits a task, when about to single-thread large/cross-cutting/repetitive work, or when you or the user ask what Claude Code can do — loads the full capability map (signal → capability) and points to the deep-dive skills.
Use when needing to understand or manage background agents, long-running tasks, polling, scheduling, or async work in Claude Code without blocking the session.
Use when you need to undo code edits, explore alternatives without losing a starting point, recover from a bad edit path, or restore previous conversation state — press Esc Esc or run /rewind to open checkpoints menu.
Use when a task is too big for one context — broad audits, multi-file migrations, multi-source research, or parallel multi-dimension review — and you want to fan out and orchestrate many subagents deterministically with the Workflow tool (requires ultracode / explicit opt-in).
Use when deciding how to work on a task - choosing effort level, model, or fast mode to balance reasoning depth, speed, and token cost.
Use when setting up or debugging Claude Code GitHub Actions automation, or deciding whether to route CI/CD tasks to GitHub Actions vs local session.
| name | claude-code-agent-sdk |
| description | Use when building custom AI agents headlessly, embedding Claude Code tools in an app, or running scripted/cron agents—need SDK package names, setup, core API entry points, supported languages, and relation to Claude Code CLI and Messages... |
| user-invocable | true |
What it is: Library for building production AI agents in TypeScript or Python with the same tools, agentic loop, and context management that power Claude Code. Same capabilities as the CLI, but programmable for headless automation, CI/CD, custom applications, and production deployments.
Packages:
@anthropic-ai/claude-agent-sdk (includes native Claude Code binary)claude-agent-sdk (requires Python 3.10+)Installation:
npm install @anthropic-ai/claude-agent-sdk
pip install claude-agent-sdk
Use Agent SDK when: productizing/automating agents headlessly, embedding tools into apps, running agents on schedule, building custom agents with full control, or agents need autonomous operation without interactive CLI.
Don't use when: interactive development (use CLI), one-off tasks (use CLI), or needing managed REST API without running infrastructure (use Managed Agents).
query()import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Fix the bug in auth.ts",
options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
console.log(message);
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Fix the bug in auth.py",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
print(message)
asyncio.run(main())
Python also supports context manager: async with ClaudeSDKClient(options=...) as client: await client.query(...)
| Option | Type | Default | Purpose |
|---|---|---|---|
allowed_tools / allowedTools | string[] | — | Pre-approve tools |
disallowed_tools / disallowedTools | string[] | — | Block tools or patterns |
permission_mode / permissionMode | string | "default" | Control approval: default, dontAsk, acceptEdits, bypassPermissions, plan, auto (TS only) |
cwd | string | cwd | Working directory |
model | string | latest Claude | Model ID |
resume | string | — | Session ID to resume |
max_turns / maxTurns | number | — | Max iterations |
hooks | object | — | Lifecycle callbacks |
agents | object | — | Subagent definitions |
mcp_servers / mcpServers | object | — | MCP server config |
setting_sources / settingSources | string[] | ["project"] | Config sources to load |
Read, Write, Edit, Bash, PowerShell, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion.
Available events (17+ total; 6 TypeScript-only):
| Event | Python | TypeScript | Purpose |
|---|---|---|---|
| PreToolUse | ✓ | ✓ | Block/modify before execution |
| PostToolUse | ✓ | ✓ | Audit/log after completion |
| PostToolUseFailure | ✓ | ✓ | Handle errors |
| PostToolBatch | — | ✓ | React to batch completion |
| UserPromptSubmit | ✓ | ✓ | Inject context |
| MessageDisplay | — | ✓ | Transform display text |
| Stop | ✓ | ✓ | Save state on exit |
| SubagentStart | ✓ | ✓ | Track spawn |
| SubagentStop | ✓ | ✓ | Aggregate results |
| PreCompact | ✓ | ✓ | Archive before compaction |
| PermissionRequest | ✓ | ✓ | Custom permissions |
| SessionStart | — | ✓ | Initialize (TS only) |
| SessionEnd | — | ✓ | Cleanup (TS only) |
| Notification | ✓ | ✓ | Forward status |
| Setup | — | ✓ | Init tasks (TS only) |
| TeammateIdle | — | ✓ | Reassign (TS only) |
| TaskCompleted | — | ✓ | React to task (TS only) |
| ConfigChange | — | ✓ | Reload settings (TS only) |
| WorktreeCreate | — | ✓ | Track worktree (TS only) |
| WorktreeRemove | — | ✓ | Cleanup worktree (TS only) |
Hooks use matcher patterns (e.g. "Write|Edit") and return hookSpecificOutput with permissionDecision, updatedInput, additionalContext, or updatedToolOutput. Note: SessionStart/SessionEnd are TypeScript-only for SDK callbacks; Python supports them only as shell command hooks in .claude/settings.json.
Spawn specialized agents via the Agent tool. Warning: when parent uses bypassPermissions, acceptEdits, or auto mode, subagents inherit it without override—grants full system access in controlled environments only.
Capture session_id from init message, resume with resume=session_id. Sessions persist as .jsonl files locally. Use resumeSessionAt to resume at specific transcript point.
Register via mcp_servers / mcpServers option or load from .claude/mcp.json / ~/.claude/mcp.json.
| Mode | Behavior |
|---|---|
default | No auto-approvals; unmatched tools trigger callback |
dontAsk | Deny instead of prompting |
acceptEdits | Auto-approve file edits + filesystem ops |
bypassPermissions | All tools run without prompts (use cautiously) |
plan | Read-only tools; Claude analyzes without editing |
auto | Model-classified approvals (TS only) |
Evaluation order: Hooks → Deny rules → Permission mode → Allow rules → Callback.
Loaded from .claude/ and ~/.claude/ when settingSources includes those paths:
.claude/skills/*/SKILL.md.claude/commands/*.md (legacy)CLAUDE.md or .claude/CLAUDE.md.claude/settings.jsonplugins option onlyPriority: api_key in options → ANTHROPIC_API_KEY env var → Third-party providers (Bedrock, AWS, Vertex AI, Azure).
Starting June 15, 2026: Agent SDK usage draws from separate monthly credit pool (distinct from interactive Claude). Credits do not roll over.
| Concept | TypeScript | Python |
|---|---|---|
| Options | Passed as object | ClaudeAgentOptions |
| camelCase | allowedTools, mcpServers | allowed_tools, mcp_servers |
| Iteration | for await (const msg of query(...)) | async for message in query(...) |
| SessionStart/End | Callback hooks | Shell command hooks only |