# Claude Code Agent SDK

> Claude Agent SDK 的定位、安装、TypeScript/Python query 用法、权限、Hooks、MCP、会话与部署边界。

URL: https://docs.passion8.cc/docs/claude-code/sdk
Language: zh-CN
Publisher: Passion8

Agent SDK 把 Claude Code 的 agent loop 做成 Python 和 TypeScript 可编程库。你可以在自己的服务、CLI、CI 或后台任务里调用同一套读文件、跑命令、改代码、管理上下文的能力。




CLI 适合人直接操作项目。Agent SDK 适合把这些能力嵌入产品、自动化任务或后台 agent 服务。




SDK 基础用法看本页。TypeScript/Python API、session API、settings 解析和迁移差异见 [Agent SDK API 参考速查](https://docs.passion8.cc/docs/claude-code/sdk-api-reference)。Agent loop、settingSources、skills、subagents、todo tracking 和 checkpointing 见 [Agent SDK Agent 能力](https://docs.passion8.cc/docs/claude-code/sdk-agent-features)。权限评估、Hooks、MCP、SessionStore、成本、OTEL、安全部署和 5m/1h 缓存策略集中在 [Agent SDK 能力矩阵](https://docs.passion8.cc/docs/claude-code/sdk-capabilities)。Custom tools、system prompt、streaming、structured output、tool search、用户审批和 SDK slash commands 见 [Agent SDK 运行时模式](https://docs.passion8.cc/docs/claude-code/sdk-runtime-patterns)。生产部署拓扑继续看 [Agent SDK 生产部署](https://docs.passion8.cc/docs/claude-code/sdk-production)。

## 什么时候用 SDK

| 需求 | 选什么 |
| --- | --- |
| 本地手工开发、让 Claude 直接改仓库 | Claude Code CLI |
| 在 Web 服务或内部平台里启动 agent | Agent SDK |
| 在 CI 中做自动修复、审查、迁移 | Agent SDK 或 `claude -p` |
| 想写自定义工具、审批、会话存储 | Agent SDK |
| 只调用纯模型 API | Claude Messages API |

## 安装





### TypeScript


```bash
npm install @anthropic-ai/claude-agent-sdk
```

TypeScript SDK 会通过 optional dependency 带上平台对应的 Claude Code binary,通常不需要单独安装 CLI。




### Python


```bash
pip install claude-agent-sdk
```

Python 需要 3.10 或更新版本。







## 认证

官方 SDK 面向 API key 和云 provider 鉴权。接 Passion8 时,本质上还是把 Anthropic 兼容入口指向网关:

```bash
export ANTHROPIC_BASE_URL="https://passion8.cc"
export ANTHROPIC_AUTH_TOKEN="sk-你的 Passion8 API Key"
```

如果你直接使用 Anthropic Console API Key,使用:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```




不要把 Claude 订阅登录和第三方产品混在一起。官方说明里,第三方开发者通常应使用 API key/provider 鉴权,不要把 claude.ai 登录额度转售或嵌入自己的 agent 产品。




## 最小示例

### TypeScript

```typescript title="agent.ts"
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "阅读当前目录,总结这个项目的用途。",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    permissionMode: "dontAsk"
  }
})) {
  if ("result" in message) console.log(message.result);
}
```

运行:

```bash
npx tsx agent.ts
```

### Python

```python title="agent.py"
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="阅读当前目录,总结这个项目的用途。",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
            permission_mode="dontAsk",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())
```

运行:

```bash
python agent.py
```

`query()` 返回 async iterator。每次迭代可能是系统消息、assistant 消息、工具调用、工具结果或最终结果。你可以流式展示,也可以收集后处理。

## 常用 options

| 选项 | TypeScript | Python | 说明 |
| --- | --- | --- | --- |
| 允许工具 | `allowedTools` | `allowed_tools` | 预批准工具 |
| 权限模式 | `permissionMode` | `permission_mode` | `acceptEdits`、`plan` 等 |
| 系统提示 | `systemPrompt` | `system_prompt` | 自定义 agent 角色 |
| MCP | `mcpServers` | `mcp_servers` | 接外部工具 |
| Hooks | `hooks` | `hooks` | 工具前后拦截 |
| 工作目录 | `cwd` | `cwd` | agent 运行目录 |

## 权限模式

| 模式 | SDK 中的用途 |
| --- | --- |
| `default` | 需要你提供审批回调 |
| `acceptEdits` | 自动接受文件编辑 |
| `plan` | 只读探索,不改源文件 |
| `dontAsk` | 未在 allowed tools 里的动作直接拒绝 |
| `auto` | TypeScript 支持,由安全分类器判断 |
| `bypassPermissions` | 仅用于 sandbox CI 或隔离环境 |

生产 agent 推荐从 `dontAsk` 或 `plan` 开始,按任务逐步放开工具。

## 内置工具

Agent SDK 可以直接使用 Claude Code 的核心工具:

| 工具 | 作用 |
| --- | --- |
| Read | 读文件 |
| Write | 新建文件 |
| Edit | 精确修改文件 |
| Bash | 跑命令 |
| Glob | 找文件 |
| Grep | 搜索内容 |
| WebSearch | 搜索网页 |
| WebFetch | 抓取页面 |
| Monitor | 监听后台脚本输出 |
| AskUserQuestion | 向用户要澄清或审批 |

## Hooks 与 MCP

SDK 也能使用 Claude Code 的扩展能力:

- Hooks:在 `PreToolUse`、`PostToolUse`、`Stop` 等节点记录、阻止、验证
- MCP:接数据库、浏览器、内部 API、项目管理系统
- Subagents:把子任务隔离到专门 agent
- Sessions:保存和恢复多轮上下文
- Prompt caching:可观察 cache 读写 token,控制 TTL

## 生产化建议

| 风险 | 建议 |
| --- | --- |
| agent 无限跑 | 设置超时、最大轮数、预算 |
| 工具过多 | 用 MCP tool search 或只开放任务需要的工具 |
| 权限过宽 | 默认 `dontAsk`,逐项 allow |
| 多租户泄露 | 每个用户隔离工作目录、环境变量和会话存储 |
| 成本不可控 | 记录 `cache_creation_input_tokens` 和 `cache_read_input_tokens` |
| 输出难解析 | 用 structured outputs 或 JSON schema |

更完整的生产部署 checklist 看 [Agent SDK 生产部署](https://docs.passion8.cc/docs/claude-code/sdk-production)。如果要做持续对话、消息队列、图片输入或插件能力,继续看 [Agent SDK Streaming 与插件](https://docs.passion8.cc/docs/claude-code/sdk-streaming-plugins)。

## 官方参考

- [Agent SDK overview](https://code.claude.com/docs/en/agent-sdk/overview.md)
- [Agent SDK quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart.md)
- [TypeScript SDK reference](https://code.claude.com/docs/en/agent-sdk/typescript.md)
- [Python SDK reference](https://code.claude.com/docs/en/agent-sdk/python.md)
- [Agent SDK permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md)

## 相关页面



- [Agent SDK API 参考速查](https://docs.passion8.cc/docs/claude-code/sdk-api-reference): TypeScript/Python 安装、query、ClaudeSDKClient、session API 和迁移。
- [Agent SDK Streaming 与插件](https://docs.passion8.cc/docs/claude-code/sdk-streaming-plugins): Streaming input、single message、插件加载、技能命名空间和缓存影响。
- [Agent SDK 运行时模式](https://docs.passion8.cc/docs/claude-code/sdk-runtime-patterns): custom tools、system prompt、structured output、tool search 和审批。