Claude Agent SDK

Claude Agent SDK 是 Anthropic 把 Claude Code 的内置工具、Agent Loop（智能体循环）和上下文管理封装成 Python / TypeScript 库的产品形态。它让开发者在自己的进程和基础设施中运行 Claude Code 风格的 Agent，而不是只通过 CLI 手动交互。

它适合构建生产自动化：Agent 可以自主读文件、执行命令、搜索代码库、编辑文件、连接 MCP 工具、维护会话上下文，并通过权限与 Hook 控制高风险动作。与普通模型 SDK 相比，它暴露的不是“发一条 prompt、拿一个回复”，而是“启动一个能连续调用工具直到完成或暂停的 Agent run”。

最小形态

Python 包名是 claude-agent-sdk，TypeScript 包名是 @anthropic-ai/claude-agent-sdk。TypeScript SDK 会通过 optional dependency 携带对应平台的 Claude Code 原生二进制，因此不要求开发者另行安装 Claude Code CLI。Python 包要求 Python 3.10 或更高版本。

典型调用围绕 query 与 ClaudeAgentOptions：

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)

asyncio.run(main())

这里的关键不在语法，而在执行边界：allowed_tools 不是给模型的建议，而是 SDK harness 允许 Agent 使用哪些工具的配置。模型选择动作，SDK 负责执行、回填结果、继续循环或结束。

内置能力

Claude Agent SDK 暴露了 Claude Code 中常见的执行能力：

能力	作用
内置工具	`Read`、`Write`、`Edit`、`Bash`、`Glob`、`Grep`、`WebSearch`、`WebFetch` 等
Hooks	在 `PreToolUse`、`PostToolUse`、`Stop`、`SessionStart`、`SessionEnd` 等生命周期点运行回调
Subagents	用 `AgentDefinition` 定义专职子智能体，并通过 `Agent` 工具委派
MCP	通过 `mcp_servers` / `mcpServers` 连接外部 Model Context Protocol（模型上下文协议）服务器
Permissions	用 allowlist、审批、只读配置等方式限制可执行动作
Sessions	捕获 `session_id` 后恢复上下文，或把 session 持久化到外部存储

这组能力说明它更接近一个 Harness Engineering（驾驭工程）库，而不是薄薄包一层 Claude API。开发者仍要对运行环境、密钥、文件系统、网络、审计和用户授权负责。

Agent Loop 形态

Claude Agent SDK 的执行流程可以概括为：

sequenceDiagram
    participant App as 应用进程
    participant SDK as Claude Agent SDK
    participant C as Claude
    participant T as 工具 / MCP / 文件系统
    App->>SDK: query(prompt, options)
    SDK->>C: prompt + 工具定义 + 会话上下文
    C-->>SDK: 工具调用或最终消息
    SDK->>T: 在权限边界内执行动作
    T-->>SDK: 观察结果
    SDK->>C: 回填工具结果并继续循环
    C-->>SDK: 最终结果 / 暂停 / 更多工具调用
    SDK-->>App: 流式消息与 result

这个循环与 Claude API Tools中的 tool_use / tool_result 属于同一类“行动-观察”结构，但抽象层不同：Messages API 让应用自己写工具循环；Agent SDK 则把 Claude Code 已经实现好的工具执行、会话和权限机制作为库暴露出来。

长时运行模式

Anthropic 的 autonomous-coding quickstart 展示了 Claude Agent SDK 的一个长时运行 harness：第一次 session 使用 initializer prompt，根据 app_spec.txt 生成 feature_list.json、init.sh、claude-progress.txt、项目结构和初始 git 状态；后续 session 使用 coding prompt，每次从全新上下文窗口开始，通过 feature list、progress file 和 git history 恢复任务状态。

这个模式的重点不是“让同一个上下文无限跑”，而是让每个新 session 都能可靠接班。feature_list.json 承担外部规格和完成状态，init.sh 承担环境恢复入口，claude-progress.txt 与 commit history 承担 Agent Memory（Agent 记忆）。后续 Agent 被要求一次只处理一个功能，验证后才把对应条目的 passes 改为 true，并在结束时提交代码和更新进度。

它说明 SDK 的产品价值不只是封装 Agent Loop（智能体循环），还在于让应用能自己组织 Long-running Agent Harness：不同 session 可以使用不同 prompt，外部文件系统保存状态，安全 hook 限制 Bash 命令，浏览器或测试工具提供端到端验证信号。

与其他 Claude 工具的边界

对象	运行位置	主要接口	适合场景
Claude Code CLI	本地交互式终端	命令行 / IDE / Web	日常开发、一次性任务、人工协作
Claude Agent SDK	开发者自己的进程与基础设施	Python / TypeScript 库	CI/CD、内部自动化、产品内 Agent
Claude Client SDK / Messages API	开发者应用	API 请求与工具调用 block	高度自定义工具循环、单次模型功能
Claude Managed Agents	Anthropic 托管基础设施	REST API / 事件流	不想自管沙箱、会话基础设施和长任务运行时的产品

Agent SDK 与 Claude Code CLI 的关系最紧：两者共享工具、Agent Loop 和上下文管理能力，只是交互面不同。CLI 面向人直接使用；SDK 面向应用把这些能力嵌入生产流程。

Agent SDK 与 Claude Client SDK 的差别在 loop 所属权。Client SDK 要求开发者自己实现工具执行循环；Agent SDK 由库运行 Agent Loop，开发者通过 options 配置工具、权限、Hook、MCP、session 和输出处理。

Claude Managed Agents 则更往托管服务方向移动：Anthropic 运行 Agent 控制面、持久 session 和 sandbox 接口，应用发送事件并接收结果。Agent SDK 仍然是在你的进程和基础设施内运行，因此更灵活，也把更多安全与运维责任留给开发者。

按官方文档当前形态，Managed Agents 的 API 围绕 agent、environment、session 和 events 组织，请求需要 managed-agents-2026-04-01 beta header。它也改变了数据责任边界：平台会保存 session history、sandbox state 和输出，因此不适用于 Zero Data Retention 或 HIPAA BAA 覆盖场景。

Claude Code 配置复用

SDK 默认会加载工作目录 .claude/ 与用户目录 ~/.claude/ 中的文件系统配置，包括：

Skill（技能）：.claude/skills/*/SKILL.md
Commands：旧格式自定义命令，官方建议新能力优先用 Skill
Memory：CLAUDE.md 或 .claude/CLAUDE.md
Plugins：通过 plugins option 以编程方式扩展 skills、agents、hooks 与 MCP servers

如果生产应用不希望继承用户本地配置，可以用 setting_sources / settingSources 限制加载来源。这个选项很关键：本地开发时复用 Claude Code 习惯很方便，但生产环境应显式决定哪些项目记忆、技能和插件能进入 Agent 上下文。

身份与品牌边界

官方文档要求第三方产品使用 API key 或支持的云提供商认证方式；除非 Anthropic 预先批准，第三方开发者不能把 claude.ai 登录或 claude.ai rate limits 提供给自己的产品用户。

品牌上，SDK 集成产品可以引用 “Claude Agent” 或 “Powered by Claude”，但不应把自己的产品称为 “Claude Code” 或 “Claude Code Agent”。这反映了一个产品边界：Claude Agent SDK 提供 Claude Code 背后的 Agent 能力，但集成后的产品仍是开发者自己的应用。

与 OpenAI Agents SDK 的对照

OpenAI Agents SDK与 Claude Agent SDK 都把 Agent run、工具、会话和可观测性抽象成库，但起点不同：

维度	Claude Agent SDK	OpenAI Agents SDK
产品来源	Claude Code 的工具执行与上下文管理	Responses API 之上的 Agent 编排层
默认工具	文件读写、Bash、搜索、编辑、MCP 等 Claude Code 工具	托管工具、函数工具、handoff、guardrails、tracing
典型场景	代码库、文件系统和本地/内部自动化	多 Agent 应用、业务函数工具、客服/运营流程
主要边界	在开发者基础设施中运行 Claude Code 风格 Agent	在应用代码中组织 OpenAI 模型与工具工作流

两者共同说明 Agent SDK 的核心价值不是“替代模型 API”，而是把工具循环、状态、权限、编排和可观测性这些重复工程固化成可复用运行时。