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 条评论

登录 后参与评论

还没有评论,来抢沙发~