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()` 呼叫的訊息流，在每個步驟報告 token 使用情況，並在末尾顯示累積估計：40下圖顯示來自單個 `query()` 呼叫的訊息流，在每個步驟報告 token 使用情況，並在末尾顯示累積估計：

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="Request flow: client to your app, which spawns a claude CLI subprocess over stdio inside the container; the subprocess writes to local disk and calls api.anthropic.com over HTTPS" 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="Request flow: client to your app, which spawns a claude CLI subprocess over stdio inside the container; the subprocess writes to local disk and calls api.anthropic.com over HTTPS" 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="Permission evaluation flow diagram" 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="Permission evaluation flow diagram" 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，以及可選的 metrics、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，以及可選的 metrics、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-TW/agent-sdk/overview) 提供與 Claude Code 相同的工具、agent 迴圈和上下文管理。它可作為 CLI 用於指令碼和 CI/CD，或作為 [Python](/zh-TW/agent-sdk/python) 和 [TypeScript](/zh-TW/agent-sdk/typescript) 套件供完整的程式控制。9[Agent SDK](/zh-TW/agent-sdk/overview) 提供與 Claude Code 相同的工具、agent 迴圈和上下文管理。它可作為 CLI 用於指令碼和 CI/CD，或作為 [Python](/zh-TW/agent-sdk/python) 和 [TypeScript](/zh-TW/agent-sdk/typescript) 套件供完整的程式控制。

14 10 

15若要以非互動模式執行 Claude Code，請傳遞 `-p` 和您的提示以及任何 [CLI 選項](/zh-TW/cli-reference)：11若要以非互動模式執行 Claude Code，請傳遞 `-p` 和您的提示以及任何 [CLI 選項](/zh-TW/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-TW/sessions)。135如需恢復旗標、`/resume` 選擇器、命名，以及當相同會話在兩個終端機中開啟時會發生什麼，請參閱[管理會話](/zh-TW/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>