Documentation 2026-06-13 21:59 UTC to 2026-06-15 23:02 UTC

16 16 

17每个代理会话都遵循相同的周期：17每个代理会话都遵循相同的周期：

18 18 

19<img src="https://mintcdn.com/claude-code/gvy2DIUELtNA8qD3/images/agent-loop-diagram.svg?fit=max&auto=format&n=gvy2DIUELtNA8qD3&q=85&s=192e1bd6c8a2950a16e5ee0b94e27e26" alt="代理循环：提示输入，Claude 评估，分支到工具调用或最终答案" width="680" height="150" data-path="images/agent-loop-diagram.svg" />19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-loop-diagram.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=1c6e8f28d80dba14a7287419656f1237" alt="代理循环：提示输入，Claude 评估，分支到工具调用或最终答案" width="720" height="212" data-path="images/agent-loop-diagram.svg" />

20 20 

211. **接收提示。** Claude 接收你的提示，以及系统提示、工具定义和对话历史。SDK 产生一个 [`SystemMessage`](#message-types)，子类型为 `"init"`，包含会话元数据。211. **接收提示。** Claude 接收你的提示，以及系统提示、工具定义和对话历史。SDK 产生一个 [`SystemMessage`](#message-types)，子类型为 `"init"`，包含会话元数据。

222. **评估并响应。** Claude 评估当前状态并确定如何继续。它可能用文本响应、请求一个或多个工具调用，或两者都有。SDK 产生一个 [`AssistantMessage`](#message-types)，包含文本和任何工具调用请求。222. **评估并响应。** Claude 评估当前状态并确定如何继续。它可能用文本响应、请求一个或多个工具调用，或两者都有。SDK 产生一个 [`AssistantMessage`](#message-types)，包含文本和任何工具调用请求。

39 39 

40下图显示了单个 `query()` 调用的消息流，在每个步骤报告令牌使用情况，末尾显示累积估计：40下图显示了单个 `query()` 调用的消息流，在每个步骤报告令牌使用情况，末尾显示累积估计：

41 41 

42<img src="https://mintcdn.com/claude-code/Dujg43sxTkuhSELI/images/agent-sdk/message-usage-flow.svg?fit=max&auto=format&n=Dujg43sxTkuhSELI&q=85&s=c542f51ff58547ef9c0e57b16d03f33c" alt="显示查询产生两个步骤消息的图表。步骤 1 有四个共享相同 ID 和使用情况的助手消息（计数一次），步骤 2 有一个具有新 ID 的助手消息，最终结果消息显示估计的 total_cost_usd。" width="760" height="520" data-path="images/agent-sdk/message-usage-flow.svg" />42<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/message-usage-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=68497aee338e01cc745323af7aea378e" alt="显示查询产生两个步骤消息的图表。步骤 1 有四个共享相同 ID 和使用情况的助手消息（计数一次），步骤 2 有一个具有新 ID 的助手消息，最终结果消息显示估计的 total_cost_usd。" width="760" height="520" data-path="images/agent-sdk/message-usage-flow.svg" />

43 43 

44<Steps>44<Steps>

45 <Step title="每个步骤产生助手消息">45 <Step title="每个步骤产生助手消息">

22 22 

23此页面上的每个托管决策都遵循 SDK 如何运行代理的方式。当您的代码调用 `query()` 时，SDK 会生成一个单独的 `claude` CLI 进程，并通过 stdio 与其通信。该子进程拥有 shell、工作目录和本地磁盘上的 JSONL 会话记录。23此页面上的每个托管决策都遵循 SDK 如何运行代理的方式。当您的代码调用 `query()` 时，SDK 会生成一个单独的 `claude` CLI 进程，并通过 stdio 与其通信。该子进程拥有 shell、工作目录和本地磁盘上的 JSONL 会话记录。

24 24 

25<img src="https://mintcdn.com/claude-code/Akpoo6g0xDlAmvHv/images/agent-sdk/hosting-subprocess.svg?fit=max&auto=format&n=Akpoo6g0xDlAmvHv&q=85&s=d348cc9687d47e0bc954075fd88d0e60" alt="请求流：客户端到您的应用，应用在容器内通过 stdio 生成 claude CLI 子进程；子进程写入本地磁盘并通过 HTTPS 调用 api.anthropic.com" width="920" height="220" data-path="images/agent-sdk/hosting-subprocess.svg" />25<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/hosting-subprocess.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=9dac857ca9d3b1410c3734900c386004" alt="请求流：客户端到您的应用，应用在容器内通过 stdio 生成 claude CLI 子进程；子进程写入本地磁盘并通过 HTTPS 调用 api.anthropic.com" width="920" height="220" data-path="images/agent-sdk/hosting-subprocess.svg" />

26 26 

27一个代理会话映射到一个子进程。运行 N 个并发会话意味着 N 个子进程，每个都有自己的进程树和记录文件。默认情况下，它们都继承您应用程序的工作目录，因此当会话需要单独的文件系统时，在每个 `query()` 调用上传递 `cwd`：27一个代理会话映射到一个子进程。运行 N 个并发会话意味着 N 个子进程，每个都有自己的进程树和记录文件。默认情况下，它们都继承您应用程序的工作目录，因此当会话需要单独的文件系统时，在每个 `query()` 调用上传递 `cwd`：

28 28 

6 6 

7> 使用 Claude Code 作为库构建生产级 AI 代理7> 使用 Claude Code 作为库构建生产级 AI 代理

8 8 

9<Note>

10 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

11</Note>

12 

13构建能够自主读取文件、运行命令、搜索网络、编辑代码等的 AI 代理。Agent SDK 为您提供了与 Claude Code 相同的工具、代理循环和上下文管理，可在 Python 和 TypeScript 中编程。9构建能够自主读取文件、运行命令、搜索网络、编辑代码等的 AI 代理。Agent SDK 为您提供了与 Claude Code 相同的工具、代理循环和上下文管理，可在 Python 和 TypeScript 中编程。

14 10 

15<CodeGroup>11<CodeGroup>

40 </Step>40 </Step>

41</Steps>41</Steps>

42 42 

43<img src="https://mintcdn.com/claude-code/FEspvVUyRuaWjm0s/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=FEspvVUyRuaWjm0s&q=85&s=a1759b0cf4541281a9fdd8f5348228e8" alt="权限评估流程图" width="920" height="260" data-path="images/agent-sdk/permissions-flow.svg" />43<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=cc94220087262cd48c9b64a14c4e1c2c" alt="权限评估流程图" width="1024" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

44 44 

45本页面重点关注 **允许和拒绝规则** 以及 **权限模式**。对于其他步骤：45本页面重点关注 **允许和拒绝规则** 以及 **权限模式**。对于其他步骤：

46 46 

159 生成长期令牌159 生成长期令牌

160</h3>160</h3>

161 161 

162<Note>

163 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

164</Note>

165 

166对于 CI 管道、脚本或其他不可用交互式浏览器登录的环境，使用 `claude setup-token` 生成一年期 OAuth 令牌：162对于 CI 管道、脚本或其他不可用交互式浏览器登录的环境，使用 `claude setup-token` 生成一年期 OAuth 令牌：

167 163 

168```bash theme={null}164```bash theme={null}

83 83 

84下面的图表显示了 Claude Code 在安装和正常操作期间如何连接到外部服务。实线表示必需的连接，而虚线表示可选或用户启动的数据流。84下面的图表显示了 Claude Code 在安装和正常操作期间如何连接到外部服务。实线表示必需的连接，而虚线表示可选或用户启动的数据流。

85 85 

86<img src="https://mintcdn.com/claude-code/RcOyXc06Ja8cuvMZ/images/claude-code-data-flow.svg?fit=max&auto=format&n=RcOyXc06Ja8cuvMZ&q=85&s=b5be40abf333defe984993af89546c19" alt="显示 Claude Code 外部连接的图表：安装/更新连接到分发服务器，用户请求连接到 Anthropic 服务，包括 Console 身份验证、public-api，以及可选的指标、Sentry 和错误报告" width="720" height="520" data-path="images/claude-code-data-flow.svg" />86<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/claude-code-data-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=5b1131530bdfdd415700a0cb4d4070c4" alt="显示 Claude Code 外部连接的图表：安装/更新连接到分发服务器，用户请求连接到 Anthropic 服务，包括 Console 身份验证、public-api，以及可选的指标、Sentry 和错误报告" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

87 87 

88Claude Code 在本地运行。为了与 LLM 交互，Claude Code 通过网络发送数据。此数据包括所有用户提示和模型输出，通过 TLS 1.2+ 在传输中加密。Claude Code 与大多数流行的 VPN 和 LLM 代理兼容。88Claude Code 在本地运行。为了与 LLM 交互，Claude Code 通过网络发送数据。此数据包括所有用户提示和模型输出，通过 TLS 1.2+ 在传输中加密。Claude Code 与大多数流行的 VPN 和 LLM 代理兼容。

89 89 

247 247 

248每个功能在会话的不同点加载。下面的选项卡解释了每个功能何时加载以及什么进入上下文。248每个功能在会话的不同点加载。下面的选项卡解释了每个功能何时加载以及什么进入上下文。

249 249 

250<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="上下文加载：CLAUDE.md 在会话开始时加载并保留在每个请求中。MCP 工具名称在启动时加载，完整架构延迟到使用。Skills 在启动时加载描述，在调用时加载完整内容。Subagents 获得隔离的上下文。Hooks 外部运行。" width="720" height="410" data-path="images/context-loading.svg" />250<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/context-loading.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=aab139e750494a237ae2e0c8f9139b0a" alt="上下文加载：CLAUDE.md 在会话开始时加载并保留在每个请求中。MCP 工具名称在启动时加载，完整架构延迟到使用。Skills 在启动时加载描述，在调用时加载完整内容。Subagents 获得隔离的上下文。Hooks 外部运行。" width="720" height="382" data-path="images/context-loading.svg" />

251 251 

252<Tabs>252<Tabs>

253 <Tab title="CLAUDE.md">253 <Tab title="CLAUDE.md">

6 6 

7> 使用 Agent SDK 从 CLI、Python 或 TypeScript 以编程方式运行 Claude Code。7> 使用 Agent SDK 从 CLI、Python 或 TypeScript 以编程方式运行 Claude Code。

8 8 

9<Note>

10 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

11</Note>

12 

13[Agent SDK](/zh-CN/agent-sdk/overview) 为您提供了与 Claude Code 相同的工具、agent 循环和上下文管理。它可作为 CLI 用于脚本和 CI/CD，或作为 [Python](/zh-CN/agent-sdk/python) 和 [TypeScript](/zh-CN/agent-sdk/typescript) 包供完整的编程控制。9[Agent SDK](/zh-CN/agent-sdk/overview) 为您提供了与 Claude Code 相同的工具、agent 循环和上下文管理。它可作为 CLI 用于脚本和 CI/CD，或作为 [Python](/zh-CN/agent-sdk/python) 和 [TypeScript](/zh-CN/agent-sdk/typescript) 包供完整的编程控制。

14 10 

15要以非交互模式运行 Claude Code，请使用 `-p` 传递您的提示和任何 [CLI 选项](/zh-CN/cli-reference)：11要以非交互模式运行 Claude Code，请使用 `-p` 传递您的提示和任何 [CLI 选项](/zh-CN/cli-reference)：

108现在假设 Claude Code 决定运行 `Bash "rm -rf /tmp/build"`。以下是发生的情况：108现在假设 Claude Code 决定运行 `Bash "rm -rf /tmp/build"`。以下是发生的情况：

109 109 

110<Frame>110<Frame>

111 <img src="https://mintcdn.com/claude-code/-tYw1BD_DEqfyyOZ/images/hook-resolution.svg?fit=max&auto=format&n=-tYw1BD_DEqfyyOZ&q=85&s=c73ebc1eeda2037570427d7af1e0a891" alt="Hook 解析流程：PreToolUse 事件触发，匹配器检查 Bash 匹配，if 条件检查 Bash(rm *) 匹配，hook 处理程序运行，结果返回到 Claude Code" width="930" height="290" data-path="images/hook-resolution.svg" />111 <img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=be0bf3053550c26de5f54cd64674c197" alt="Hook 解析流程：PreToolUse 事件触发，匹配器检查 Bash 匹配，if 条件检查 Bash(rm *) 匹配，hook 处理程序运行，结果返回到 Claude Code" width="930" height="270" data-path="images/hook-resolution.svg" />

112</Frame>112</Frame>

113 113 

114<Steps>114<Steps>

16 16 

17当您给 Claude 一个任务时，它会经历三个阶段：**收集上下文**、**采取行动**和**验证结果**。这些阶段相互融合。Claude 始终使用工具，无论是搜索文件以了解您的代码、编辑以进行更改，还是运行测试以检查其工作。17当您给 Claude 一个任务时，它会经历三个阶段：**收集上下文**、**采取行动**和**验证结果**。这些阶段相互融合。Claude 始终使用工具，无论是搜索文件以了解您的代码、编辑以进行更改，还是运行测试以检查其工作。

18 18 

19<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/agentic-loop.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=5f1827dec8539f38adee90ead3a85a38" alt="代理循环：您的提示导致 Claude 收集上下文、采取行动、验证结果，并重复直到任务完成。您可以在任何时刻中断。" width="720" height="280" data-path="images/agentic-loop.svg" />19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agentic-loop.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=4a30fb7ce2815012a9f27c955e2c6bb0" alt="代理循环：您的提示导致 Claude 收集上下文、采取行动、验证结果，并重复直到任务完成。您可以在任何时刻中断。" width="720" height="280" data-path="images/agentic-loop.svg" />

20 20 

21循环会根据您的要求进行调整。关于您代码库的问题可能只需要收集上下文。错误修复会循环通过所有三个阶段多次。重构可能涉及广泛的验证。Claude 根据从前一步学到的内容决定每一步需要什么，将数十个操作链接在一起并沿途进行纠正。21循环会根据您的要求进行调整。关于您代码库的问题可能只需要收集上下文。错误修复会循环通过所有三个阶段多次。重构可能涉及广泛的验证。Claude 根据从前一步学到的内容决定每一步需要什么，将数十个操作链接在一起并沿途进行纠正。

22 22 

130 130 

131使用 `claude --continue` 或 `claude --resume` 恢复会话会在相同的会话 ID 下重新打开它，并将新消息附加到现有对话。使用 `--fork-session` 或 `/branch` 分叉会将历史复制到新的会话 ID 中，保持原始会话不变。131使用 `claude --continue` 或 `claude --resume` 恢复会话会在相同的会话 ID 下重新打开它，并将新消息附加到现有对话。使用 `--fork-session` 或 `/branch` 分叉会将历史复制到新的会话 ID 中，保持原始会话不变。

132 132 

133<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/session-continuity.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=fa41d12bfb57579cabfeece907151d30" alt="会话连续性：恢复继续相同的会话，分叉创建一个具有新 ID 的新分支。" width="560" height="280" data-path="images/session-continuity.svg" />133<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/session-continuity.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=04ed0984a58e4127e05b3640265241a3" alt="会话连续性：恢复继续相同的会话，分叉创建一个具有新 ID 的新分支。" width="560" height="280" data-path="images/session-continuity.svg" />

134 134 

135有关恢复标志、`/resume` 选择器、命名以及当相同会话在两个终端中打开时会发生什么，请参阅[管理会话](/zh-CN/sessions)。135有关恢复标志、`/resume` 选择器、命名以及当相同会话在两个终端中打开时会发生什么，请参阅[管理会话](/zh-CN/sessions)。

136 136 

6 6 

7> Claude Code 的法律协议、合规认证和安全信息。7> Claude Code 的法律协议、合规认证和安全信息。

8 8 

9<Note>

10 Starting June 15, 2026, Agent SDK and `claude -p` usage on subscription plans will draw from a new monthly Agent SDK credit, separate from your interactive usage limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) for details.

11</Note>

12 

13<h2 id="legal-agreements">9<h2 id="legal-agreements">

14 法律协议10 法律协议

15</h2>11</h2>