结论先说
- 逐字流式渲染靠开启
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 条评论
还没有评论,来抢沙发~