Agent SDK

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 鉴权。接 Gushen888 时,本质上还是把 Anthropic 兼容入口指向网关:

export ANTHROPIC_BASE_URL="https://api.gushen888.cloud"
export ANTHROPIC_AUTH_TOKEN="sk-你的 Gushen888 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

更完整的生产部署 checklist 看 Agent SDK 生产部署。如果要做持续对话、消息队列、图片输入或插件能力,继续看 Agent SDK Streaming 与插件。

官方参考

• Agent SDK overview
• Agent SDK quickstart
• TypeScript SDK reference
• Python SDK reference
• Agent SDK permissions

相关页面

Agent SDK API 参考速查TypeScript/Python 安装、query、ClaudeSDKClient、session API 和迁移。Agent SDK Streaming 与插件Streaming input、single message、插件加载、技能命名空间和缓存影响。Agent SDK 运行时模式custom tools、system prompt、structured output、tool search 和审批。