用 Next.js 实现工具型 Agent 流式交互
文章使用 Anthropic 官方 SDK、Next.js 路由处理器与 React,通过 SSE 传输文本及工具调用等事件。客户端以 fetch 发起 POST 并解析事件流,同时讨论真实代理环境下的实现细节。
AI 深度解读
把 Claude 的回答逐字显示到页面上,只解决了 Agent 交互的一部分。调用工具时如何展示进度、多轮执行如何统计用量、用户点停止后请求能否取消,以及线上代理为何把流攒成整段返回,才是这篇原文关注的问题。
作者给出的方案是:在 Next.js App Router 中,用官方 @anthropic-ai/sdk 执行工具循环,通过 SSE 把过程传给 React。它值得读的地方,是把协议、执行和部署串了起来;但示例仍有几个缺口,直接复制还不足以完成生产接入。
为什么选 SSE,却不用 EventSource
SSE(Server-Sent Events)是在普通 HTTP 响应里持续发送文本,响应类型为 text/event-stream。一条消息由字段行组成,以空行结束。
这很适合原文的交互:浏览器提交一次任务,服务端持续推送回答、工具状态和用量,执行途中无需浏览器继续发送消息。在这个前提下,引入 WebSockets 的连接升级和另一套通信机制,收益有限。如果产品需要执行中追加指令,就要重新评估这个前提。
SSE 也不等于浏览器的 EventSource。后者只支持 GET,不能设置请求体或自定义 Authorization 请求头。聊天消息需要放进 POST body,因此作者用 fetch() 发请求,再自行解析响应流;原文称解析器约 30 行。
协议应该描述 Agent 正在做什么,而不只是传递回答文本。
下面这段类型定义,让服务端能够发送的事件有明确边界:
export type AgentEvent =
| { event: "meta"; data: { conversationId: string } }
| { event: "text"; data: { delta: string } }
| { event: "tool_call"; data: { name: string; input: unknown } }
| { event: "tool_result"; data: { name: string; result: unknown; isError: boolean } }
| { event: "usage"; data: { inputTokens: number; outputTokens: number; cacheRead: number; cacheWrite: number } }
| { event: "error"; data: { code: string; message: string } }
| { event: "done"; data: Record<string, never> };
const sse = (ev: AgentEvent) => `event: ${ev.event}\ndata: ${JSON.stringify(ev.data)}\n\n`;
要留意最后一行的 \n\n,它才是事件边界。JSON.stringify() 会转义字符串里的换行,因此这里能保持每条事件只有一行 data:。
这些事件都对应界面需求:meta 提前交付会话 ID,tool_call 和 tool_result 支撑工具进度展示,usage 更新用量,error 提供机器可读的错误码,done 区分正常完成与连接意外中断。
不过,原文 handler 没有实际发送 meta,客户端也没有处理 done。协议设计与示例实现之间,还差这两处接线。
工具循环怎样接上页面,也接上停止按钮
作者的 runAgent() 沿用常见工具循环:请求模型,执行模型要求的工具,把结果交回模型,再继续。页面需要知道的节点,通过 onText、onToolCall、onToolResult 和 onTurn 回调暴露出来。
示例调用 client.messages.stream(),模型写为 claude-sonnet-5-5,max_tokens: 8192,最多执行 12 轮,超出后抛出 Agent exceeded 12 turns。这些是原文参数;原文没有给出 Next.js 或 SDK 的具体版本。
同轮工具通过 Promise.all 并行执行,结果统一放进一条 role: "user" 消息。作者称,拆成多条消息会让 Claude 停止并行调用工具,但没有提供对照数据。工具失败时,代码返回带 is_error: true 的 tool_result,让模型有机会读取错误并调整后续操作。
文本和工具通知的时机也不同。stream.on("text") 持续交付文本增量,完整工具参数则等 finalMessage() 返回后取得。因此,这个界面展示的是完整调用信息,不能据此认为工具参数也在逐步流式呈现。
停止按钮依靠一条取消链路:浏览器用 AbortController 给 fetch() 传入 signal,服务端再把 req.signal 交给 SDK。作者希望浏览器断开后,正在执行的模型请求随之取消,避免继续生成到输出上限。
这里要补一个边界:示例的 runTool(call.name, call.input) 没有接收取消信号。模型请求取消,并不代表数据库查询、外部接口请求等工具操作也会停止。
用量同样要分清。onTurn 在每轮模型结束后发送 input_tokens、output_tokens、cache_read_input_tokens 和 cache_creation_input_tokens,映射到协议的四个字段,两个缓存字段缺失时按 0 处理。它提供的是逐轮 token 记录,没有实现价格换算和预算拦截;12 轮上限也不能直接当成费用上限。
本地能流式,为什么上线就变成整段返回
Next.js 路由用 ReadableStream<Uint8Array> 输出事件,并设置 runtime = "nodejs"、dynamic = "force-dynamic"、maxDuration = 300。最后一个配置用于提高读取它的宿主平台的执行时限,原文举例是 Vercel。
响应头则包括:
Content-Type: text/event-stream; charset=utf-8声明响应格式。Cache-Control: no-cache, no-transform表达缓存与禁止转换要求。Connection: keep-alive表达保持连接的意图。X-Accel-Buffering: no用于要求 nginx 风格的代理关闭缓冲。
作者指出,压缩中间件与代理缓冲是线上流式失效的常见原因。不过,这些响应头能否生效仍取决于部署链路,原文没有提供不同代理配置下的测试结果。
错误处理也存在时间边界。流开始前,可以返回带真实状态码的 JSON,例如未登录返回 401、限流返回 429。一旦已经发出 200 流式响应,业务失败就需要通过 error 事件通知客户端。
浏览器端的关键,是不要把一次网络读取当成一条事件。下面的解析器用缓冲区处理拆包与合包:
async function* readSse(body: ReadableStream<Uint8Array>) {
const reader = body.getReader();
const decoder = new TextDecoder();
let buf = "";
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buf += decoder.decode(value, { stream: true });
let idx: number;
while ((idx = buf.indexOf("\n\n")) !== -1) {
const chunk = buf.slice(0, idx);
buf = buf.slice(idx + 2);
let event = "message";
let data = "";
for (const line of chunk.split("\n")) {
if (line.startsWith("event:")) event = line.slice(6).trim();
else if (line.startsWith("data:")) data += line.slice(5).trim();
}
yield { event, data: data ? JSON.parse(data) : null };
}
}
}
要重点看 decoder.decode(value, { stream: true }):中文字符的字节可能跨两次读取,它负责保留尚未解码完整的部分。buf.indexOf("\n\n") 则保证只在事件结束时切分消息。
这个解析器适合原文自定义的单行 JSON、LF 分隔协议。它没有完整覆盖通用 SSE 的多行 data:、其他换行形式,以及读取结束时残留数据的处理,不宜直接作为通用解析库。
我的判断
我认可这篇把事件协议放在界面实现前面的做法。对工具型 Agent,用户不仅需要答案,还需要知道任务是否在推进、哪里失败、何时结束。把这些状态明确写成事件,比让前端猜测文本内容更容易维护。
原文也没有提供性能基准、费用对照或部署压测。关于并行调用行为、代理缓冲和取消效果的描述,应当视为实现建议,不能当成覆盖所有环境的验证结论。claude-sonnet-5-5 的名称也只是原文给出的配置,输入材料不足以确认其可用性。
共享 AgentEvent 类型有帮助,但作者说新增事件会一直报类型错误,直到两端都处理,表述过强。示例客户端使用普通 if/else,没有穷尽检查,漏处理新事件未必会报错。
产品侧的两条提醒则很实用:执行结束后再保存最终消息列表,可以减少逐增量写数据库的开销,但异常中断时如何恢复,原文没有展开;工具结果应按需发送摘要或状态,因为原始结果可能包含内部 ID、其他客户的数据。示例直接发送完整 result,正式接入时需要收紧。
能拿来做什么
- 给 Next.js 聊天接口增加工具状态事件,让 React 能展示调用开始、成功和失败,并补上
meta、done的实际处理及缺少done时的中断提示。 - 把停止按钮接通到 SDK,再检查 Node 工具函数是否支持取消;涉及写操作时,明确停止后已经执行的动作如何反馈给用户。
- 上线时分别检查事件到达时间、代理缓冲、函数超时和断开后的模型请求状态,不要只验证最终答案是否正确。
- 在服务端累计每轮
usage,限制工具结果暴露范围,并按产品对恢复能力的要求选择落库时机。