Claude Agent SDK 是把 Claude Code 从终端协作工具变成可编程 Agent 引擎的官方接口。CLI 适合人坐在终端里和 Claude 一起改代码；Agent SDK 适合把 Claude 放进系统、服务、CI/CD、内部平台和自动化流程里。
什么时候该用 Agent SDK？
如果你的需求是一次性的本地协作，直接用 claude CLI 即可。如果你需要程序化地创建、运行、监控和消费 Claude 的输出，就应该考虑 SDK。
典型场景：
- CI 失败后自动分析原因并给出修复建议
- 在内部平台里提供“让 AI 修这个 issue”的按钮
- 把代码审查、文档生成、测试补齐做成后台任务
- 从 GitHub/GitLab webhook 接收事件后自动启动 Agent
- 构建面向团队的 AI worker，而不是只服务单个开发者
TypeScript 最小示例
ts
import { query } from '@anthropic-ai/claude-agent-sdk'
for await (const message of query({
prompt: 'Analyze this repository and summarize the architecture',
options: {
cwd: '/path/to/repo'
}
})) {
console.log(message)
}SDK 返回 async iterator，意味着你可以边运行边消费消息，把进度实时显示在 Web UI、日志系统或任务面板里。
Python 最小示例
python
import asyncio
from claude_agent_sdk import query
async def main():
async for message in query(
prompt='Find risky code paths in this repository',
options={'cwd': '/path/to/repo'}
):
print(message)
asyncio.run(main())Python 版本适合后端自动化、数据平台和 CI glue code；TypeScript 版本适合 Node 服务、开发平台和前端团队内部工具。
权限设计：生产环境的核心
生产级 Agent 的关键不是“能做很多事”，而是“只允许它做这次任务需要做的事”。
代码审查任务只需要读权限：
ts
query({
prompt: 'Review this pull request for security issues',
options: {
cwd: '/repo',
allowedTools: ['Read', 'Grep', 'Glob', 'Bash(git diff *)'],
disallowedTools: ['Write', 'Edit', 'Bash(git push *)']
}
})自动修复任务才需要 Edit 或 Write。创建 PR 的任务再额外允许 Git/GitHub/GitLab 相关命令。不要给所有 Agent 默认全权限。
结构化输入与结构化输出
不要只传一句模糊 Prompt：
text
fix the bug更好的输入应该包含任务、仓库、分支、日志、限制和交付物：
json
{
"task": "fix_test_failure",
"repository": "acme/payments",
"branch": "feature/refactor-auth",
"failing_job": "unit-tests",
"constraints": ["do not modify public API", "add regression test"]
}输出也应固定格式，便于系统消费：
text
Return JSON with keys: summary, changed_files, risks, next_steps.与 MCP 的组合
Agent SDK 负责驱动 Agent，MCP 负责连接外部工具。一个生产级自动修复系统可能这样运行：
- Webhook 收到 Sentry issue
- SDK 启动 Claude Agent
- MCP 获取 Sentry stack trace 和 GitHub issue
- Claude 定位代码并生成修复
- SDK 收集结果并创建 PR
- 人类 review 后合并
这样 Claude 不再是“本地助手”，而是企业研发平台里的一个可审计 worker。
生产最佳实践
- 每个任务使用独立工作目录或临时 clone
- 按任务最小化工具权限
- 对外部 Issue、网页、日志内容当作不可信输入处理
- 所有代码变更走 PR，不直接合并主分支
- 记录完整消息流，便于审计和复盘
- 密钥放 Secrets，不进入 Prompt
- 长任务用流式输出，避免黑盒等待
来源：Claude Code 官方文档 - Agent SDK | 整理：ClaudeEagle