Claude Code

Agent SDK

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

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

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

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

#什么时候用 SDK

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

#安装

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

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

pip install claude-agent-sdk

Python 需要 3.10 或更新版本。

#认证

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

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

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

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

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

#最小示例

#TypeScript

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);
}

运行:

npx tsx agent.ts

#Python

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())

运行:

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