Claude Agent SDK 流式輸出、工具權限審批(canUseTool)與會話恢復怎麼寫

把 Claude Agent SDK 接入正式業務時,怎麼做到逐字打字機渲染、前端彈窗審批危險工具、跨請求恢復多輪上下文?本文按官方文檔給出 TypeScript 與 Python 的流式輸出、canUseTool 回調與 resume/forkSession 完整寫法。

NNathaniel bigo··原創首發·AI 輔助撰寫
11 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 其他 帳號

結論先說

  1. 逐字流式渲染靠開啟 includePartialMessages: true:預設 query() 每完成一整塊消息才吐出一次;打開該開關後會額外推送 stream_event 增量分片,可直接拿 text_delta 驅動前端打字機效果。
  2. 動態審批用 canUseTool(Python 為 can_use_tool)回調:對未被靜態規則決定的工具調用,回調既能返回 allow 並順手改寫消毒入參(updatedInput),也能返回 deny 把拒絕原因喂回給模型讓它換思路。
  3. 跨請求續接對話靠儲存 session_id 並傳入 resume:首輪從初始化消息或最終 result 裏存下 session_id,下一輪傳 resume: sessionId 即可無縫接上歷史記錄。
  4. 想保留原對話分支做實驗就加 forkSession: true:配合 resume 使用時會克隆一份歷史並生成全新的分支會話 ID,不污染原主線。
  5. Claude Code 訂閱與高配額開通入口:國內無境外卡可通過本站 iOS 免上號自助卡密開通 Claude Pro 會員 或 5 倍以上額度的 Claude Max 會員,完整檔位選型見 Claude Code 訂閱說明頁。

Agent SDK 工具權限判定順序

圖:本站根據 Claude Agent SDK 官方文檔:Configure permissions 整理的示意圖

本文根據 Claude Code 官方文檔《Streaming output》《Configure permissions》《Session management》《Agent SDK overview》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Anthropic 官方網站。

適用於誰

  • 已經跑通了第一個 Demo,準備把 Claude Agent SDK 做進內部研發平台或 Web 介面,需要實時打字機流式輸出的開發者;
  • 不敢在後端直接開 bypassPermissions,想用 canUseTool 攔截 Bash 或寫文件請求、推送到前端讓人工點「批准 / 拒絕」的人;
  • 搜「claude agent sdk 會話恢復」「agent sdk resume forkSession」,想在多次 HTTP 請求之間保持多輪記憶的人。

如果你還沒裝包或沒跑過基礎示例,請先看入門篇 Claude Agent SDK 入門:是什麼、怎麼裝、第一個智能體。

一、開啟逐字流式輸出(includePartialMessages)

和直接調底層接口類似(原生客戶端流式對比見 Claude API TypeScript 快速上手 與 Claude API Python 入門),Agent SDK 預設為了方便腳本處理,只在模型寫完一段話或填完整個工具參數後才返回一條完整的 assistant 消息。做聊天介面時頁面會顯得卡頓好幾秒才整段蹦字。

把 includePartialMessages 設為 true 後,異步迭代器會實時吐出 type === "stream_event" 的增量事件:

typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const msg of query({
  prompt: "讀取 package.json 並簡述項目依賴結構",
  options: {
    allowedTools: ["Read"],
    includePartialMessages: true,
  },
})) {
  if (msg.type === "stream_event") {
    const evt = msg.event;
    if (evt.type === "content_block_delta" && evt.delta.type === "text_delta") {
      process.stdout.write(evt.delta.text); // 實時逐字輸出
    }
  } else if (msg.type === "result") {
    console.log(`\n執行結束,會話 ID:${msg.session_id}`);
  }
}

注意開啟增量流之後,原本完整的 assistant 消息依然會在每個塊結束時照常發出。前端渲染時不要把 text_delta 拼出來的文字和隨後的 assistant 全量文本重複追加兩遍;實戰裏常見的做法是用流式增量做實時草稿展示,收到完整 assistant 塊後再用定稿內容替換臨時緩衝區,同時還能從 input_json_delta 裏提前預覽模型正在拼裝的工具參數。

二、用 canUseTool 實現人工審批與入參改寫

了解過終端權限模式的人都知道靜態規則能擋住大部分常規風險(規則語法見 Claude Code 權限模式詳解)。在 SDK 裏,凡是沒有被 disallowedTools 拒絕、也沒有被 allowedTools 或自動模式提前放行的工具請求,都會落到你傳入的 canUseTool 異步函數里。

回調函數支持三種常見動作:原樣放行、改寫參數後放行(例如強制給命令加上只讀標誌或收窄寫入目錄)、帶理由拒絕:

typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const msg of query({
  prompt: "清理臨時構建目錄並檢查當前分支狀態",
  options: {
    allowedTools: ["Read", "Glob"], // 只讀工具免審直通
    canUseTool: async (toolName, input) => {
      if (toolName === "Bash") {
        const cmd = String(input.command ?? "");
        if (cmd.includes("rm -rf")) {
          return {
            behavior: "deny",
            message: "安全策略禁止執行 rm -rf,請僅列出待清理文件清單交由用戶確認。",
          };
        }
        // 這裏也可以掛起等待前端 WebSocket 人工點擊批准後再返回 allow
        return {
          behavior: "allow",
          updatedInput: input,
        };
      }
      return { behavior: "allow", updatedInput: input };
    },
  },
})) {
  if (msg.type === "result") console.log(msg.subtype);
}

在 Python SDK(claude-agent-sdk)中機制完全一致,只需導入 PermissionResultAllow 與 PermissionResultDeny,在 ClaudeAgentOptions(can_use_tool=...) 裏返回對應實例即可。需要注意:如果把 permissionMode 設成了 "dontAsk",未預批准的工具會被直接拒絕而不會走進回調;使用 canUseTool 時保持預設的 "default" 或 "acceptEdits" 模式即可。

三、儲存 session_id 實現會話恢復與分支克隆

Agent SDK 三種會話續接方式對比

圖:本站根據 Claude Agent SDK 官方文檔:Session management 整理的示意圖

每次調用 query() 啟動新對話時,SDK 都會分配一個唯一的 session_id(可在首條 type === "system" 且 subtype === "init" 的消息或末尾 result 消息中讀取)。把它存進你的業務數據庫,用戶下一輪發消息時傳入 resume 就能恢復完整上下文。

下面是 Python 端先跑第一輪分析、再通過 resume 和 fork_session 派生新分支修改代碼的寫法:

python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def run_workflow():
    session_id = None

    # 第一輪:只讀定位問題並記錄 session_id
    async for msg in query(
        prompt="分析 auth.py 裏令牌校驗邏輯的邊界漏洞,先不改文件。",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Grep"]),
    ):
        if isinstance(msg, ResultMessage):
            session_id = msg.session_id

    # 第二輪:基於上一輪記憶派生獨立分支執行修改,原會話歷史保持不變
    async for msg in query(
        prompt="按剛才找出的第一處漏洞,在 auth.py 裏補上過期時間判斷。",
        options=ClaudeAgentOptions(
            resume=session_id,
            fork_session=True,
            allowed_tools=["Read", "Edit"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(msg, ResultMessage):
            print("新分支會話 ID:", msg.session_id)

asyncio.run(run_workflow())

順便提醒計費合規邊界:按官方條款,企業或第三方應用集成 Agent SDK 必須使用按量計費的 API Key 或雲廠商網關;如果你平時只是在自己電腦終端裏用交互式命令行寫代碼,則可以直接使用固定週期額度的個人訂閱,需要開通或續期可查看本站 Claude Code 充值頁 或 Claude Pro 方案。

常見問題

問:設定了 allowedTools: ["Bash"] 之後,為什麼 Bash 命令不再觸發 canUseTool 回調了?

答:因為 allowedTools 屬於靜態預批准白名單,優先級排在 canUseTool 之前。凡是需要走動態代碼審批的工具,不要放進 allowedTools 數組裏。

問:後端部署在無狀態容器裏,resume 為什麼報找不到舊會話?

答:Agent SDK 的會話記錄預設以本地文件形式儲存在運行目錄對應的 .claude 會話存儲下。多實例容器部署時需掛載共享持久化存儲卷,或固定同一用戶的路由節點。

問:deny 返回裏的 interrupt: true 有什麼用?

答:預設不設 interrupt 時,拒絕原因會作為工具結果回傳給模型,讓模型嘗試換別的合規辦法繼續完成任務;若檢測到嚴重違規想立刻掐斷整輪循環,加上 interrupt: true 會直接終止本次 query。

問:國內沒有海外銀行卡,怎麼給 Claude Code 開通 Pro 或 Max 訂閱?

答:可在 Claude Code 訂閱頁 選擇走 iOS 訂閱鏈路的 Claude Pro 自助卡密 或 Claude Max 充值,支持支付寶、微信支付與 AlipayHK,無需交出帳號密碼;若帳號彈出身份核驗也可查看 Claude KYC 認證人工協助(失敗不收費,封號不在質保範圍)。

相關教學

參考資料

  • Claude Agent SDK 官方文檔:Streaming output — https://code.claude.com/docs/en/agent-sdk/streaming-output
  • Claude Agent SDK 官方文檔:Configure permissions — https://code.claude.com/docs/en/agent-sdk/permissions
  • Claude Agent SDK 官方文檔:Session management — https://code.claude.com/docs/en/agent-sdk/sessions
  • Claude Agent SDK 官方文檔:Overview — https://code.claude.com/docs/en/agent-sdk/overview

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同產品的其他教學

  1. 01

    Anthropic Contextual Retrieval(上下文增強檢索)是什麼、怎麼實現:給文檔塊自動補背景摘要結合緩存降失誤率

    長文檔切成小塊後丟了公司名、年份和主語指代導致 RAG 頻頻搜錯?本文按 Anthropic 官方技術文章詳解 Contextual Retrieval 原理、官方公開評測失誤率下降 49% 至 67% 的組合架構,以及用 Claude 提示詞緩存低成本批量生成切片背景的完整 Python 代碼。

    Claude其他 AI 工具0
  2. 02

    RAG 知識庫回答不準怎麼調優:切片大小(Chunking)、BM25 + 向量混合檢索與 Rerank 重排序三步排查法

    搭好的 RAG 企業知識庫一問具體型號、報錯碼或跨行表格就答非所問?本文按 OpenAI 與 Anthropic 官方檢索文檔,給出先隔離檢索與生成故障、再按結構化切片(Chunking)、BM25 加向量混合召回(RRF)與 Rerank 重排序逐層調優的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 開源本地部署(Docker Compose)與提示詞版本管理(Prompt Management)從零上手教學

    企業內網嚴禁業務日誌出境,又想免費擁有大模型調用鏈追蹤與不發版熱更新提示詞的能力?本文按 Langfuse 官方文檔整理 Docker Compose 本地一鍵啟動(含 ClickHouse 架構注意事項)、密鑰配置與 Prompt Management 標籤化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入門教學:給 LangGraph 與原生 OpenAI / Claude 接口加調用鏈追蹤、Token 成本統計與免費層限額

    智能體多步調用總是找不到哪一輪提示詞跑偏、單次請求到底燒了多少 Token?本文按 LangSmith 官方文檔講清環境變量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 與 @traceable 追蹤原生接口,以及 Developer 免費層額度與留存規則。

    Claude其他 AI 工具0
  5. 05

    Zotero 搭配 Claude / ChatGPT 高效讀英文文獻:PDF 翻譯插件、批註導出精讀與防捏造參考文獻流程

    在 Zotero 裏讀英文頂會論文怎麼無縫聯動 Claude 與 ChatGPT?本文整理 Translate for Zotero 劃詞翻譯配置、高亮批註導出精讀提示詞,以及杜絕 AI 捏造假 DOI 參考文獻的核驗閉環。

    Claude其他 AI 工具0
  6. 06

    Obsidian 接入 Claude、ChatGPT 與本地 Ollama 做個人雙鏈筆記問答:主流插件配置與私隱脫敏邊界

    想在 Obsidian 裏基於自己的雙鏈筆記庫做 AI 問答又擔心私隱外泄?本文對比 Copilot 與 Smart Connections 插件,整理接入 Claude、OpenAI 官方 API 與本地 Ollama 的步驟及敏感目錄隔離規則。

    Claude其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~