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

圖:本站根據 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 實現會話恢復與分支克隆

圖:本站根據 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 入門:是什麼、怎麼裝、第一個智能體
- Claude Code 權限模式詳解:auto、手動、plan、bypass 與權限規則配置
- Claude API TypeScript / Node.js 快速上手:流式、重試與超時
- Claude API Python 入門:安裝 SDK、第一個請求與流式輸出
參考資料
- 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
0 條評論
還沒有評論,來搶沙發~