如何用 Mastra 的 Agent.stream() 流式输出代理响应并消费 textStream【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra在 Mastra 项目中Agent 注册完成后默认用.generate()要等全部步骤和工具调用完成才返回完整响应如果你希望响应在生成过程中就逐步到达聊天界面、长文本生成、需要即时反馈的场景应改用Agent.stream()。它返回一个MastraModelOutput其中的textStream会把响应拆成增量文本块chunk你可以用for await循环逐块消费流结束后再取完整文本、用量等结果。这篇指南基于 Mastra 官方文档 Streaming 指南 与 Agent.stream() 参考。示例代码依赖mastra/core包如需把流转换成 AI SDK 格式还会用到文档 frontmatter 中列出的mastra/ai-sdk包。准备创建并注册一个 Agent流式调用前提是你有一个可用的 Agent。按 Agents 文档 的做法用mastra/core/agent中的Agent类创建并注册到 Mastra 实例import { Agent } from mastra/core/agent export const testAgent new Agent({ id: test-agent, name: Test Agent, instructions: You are a helpful assistant., model: __GATEWAY_OPENAI_MODEL__, })model按文档说明以provider/model-name形式指定官方文档源码中用__GATEWAY_OPENAI_MODEL__作为占位符使用时替换成你实际接入的模型字符串。import { Mastra } from mastra/core import { testAgent } from ./agents/test-agent export const mastra new Mastra({ agents: { testAgent }, })调用时文档建议用mastra.getAgentById()取回 Agent这样它能访问实例级的共享服务存储、日志、Agent 注册表直接 import 的 Agent 只能用本地配置拿不到这些共享服务。调用 stream() 并逐块消费 textStreamstream()的第一个参数是messages支持四种形式见 stream 参考的参数表单个字符串、字符串数组或带role/content的消息对象数组以及AiMessageType[]、UIMessageWithMetadata[]。单条字符串最简单多条上下文用数组需要精确控制角色和对话流时用消息对象数组。最短主路径调用stream()用for await遍历textStreamconst agent mastra.getAgentById(test-agent) const stream await agent.stream([{ role: user, content: Help me organize my day }]) for await (const chunk of stream.textStream) { process.stdout.write(chunk) }这里的关键区别是textStream的类型是ReadableStreamstringMastraModelOutput 参考 说明它只输出增量文本内容已经过滤掉了元数据、工具调用和控制块如果你需要看到工具调用、推理等所有事件应改用下一节介绍之外的fullStream见后文“可选检查完整事件流”。运行后终端会随生成进度逐段打印代理回复。下面是官方文档给出的示例输出文档示例实际内容取决于模型Of course! To help you organize your day effectively, I need a bit more information. Here are some questions to consider: ...流结束后取完整结果MastraModelOutput除了流式属性外还有一组 promise 属性它们在流结束后才 resolve见 MastraModelOutput 参考属性类型说明stream.textPromisestring模型返回的完整拼接文本stream.stepsPromise完成的模型步骤列表stream.usagePromiseLanguageModelUsagetoken 用量含inputTokens、outputTokens、totalTokens推理模型另有可选的reasoningTokensstream.finishReasonPromisestring \| undefined停止原因stop、length、tool_calls、content_filter流未结束时为undefinedstream.objectStream/stream.object—传入structuredOutput时的部分/最终结构化输出也就是说你可以一边消费textStream一边在流结束后await stream.text拿到完整文本做后续处理const stream await agent.stream(Write a haiku) for await (const text of stream.textStream) { process.stdout.write(text) } const fullText await stream.text console.log(fullText)如果只关心 promise 结果、不想自己遍历 chunk可以手动消费整条流consumeStream()会完成流消费并触发 promise 属性 resolve其可选参数onError用于接收流错误const stream await agent.stream(Analyze this data) try { await stream.consumeStream({ onError: error { console.error(Stream error:, error) }, }) const result await stream.text } catch (error) { console.error(Failed to get result:, error) }另一种排查方式是检查错误属性stream.error为undefined表示没有出错否则保存字符串消息、Error对象或带堆栈的序列化错误。也可以用stream.getFullOutput()一次性拿到text、object、toolCalls、toolResults、usage、reasoning、finishReason、response的汇总对象。可选检查完整事件流 fullStream如果需要调试或向用户展示中间过程开始、工具调用、步骤边界遍历stream.fullStream可以看到所有事件块。每个块都带type以及可选的from、payload字段见 ChunkType 参考const agent mastra.getAgentById(test-agent) const stream await agent.stream([{ role: user, content: Help me organize my day }]) for await (const chunk of stream.fullStream) { console.log(chunk) }Agent 常见事件包括start运行开始、text-start/text-delta/text-end文本生成的边界与增量增量文本在 delta 块中、reasoning-start/reasoning-delta/reasoning-end、tool-call与tool-result、step-start/step-finish模型步骤开始与结束、finish运行完成。该列表不完整完整块类型以ChunkType参考为准。下面是官方文档展示的示例事件文档示例字段值会随运行变化{ type: start, from: AGENT, // .. } { type: step-start, from: AGENT, payload: { messageId: msg-cdUrkirvXw8A6oE4t5lzDuxi, // ... } } { type: tool-call, from: AGENT, payload: { toolCallId: call_jbhi3s1qvR6Aqt9axCfTBMsA, toolName: testTool // .. } }选择依据只要展示文本就用textStream需要区分工具调用、推理等阶段例如在 UI 中渲染进度才用fullStream并可以按chunk.type分支处理。限制与注意事项模型版本stream()面向 V2 模型。V1 模型应使用streamLegacy()框架会自动检测模型版本不匹配时抛出错误见 stream 参考。后台任务场景对会派发后台任务的 Agent文档建议使用untilIdle: true选项让流在后台任务完成、Agent 有机会响应结果之前保持打开。该选项要求配置了 agent memory。回调onFinish、onStepFinish、onChunk、onError、onAbort等回调作为stream()第二参数的 options 传入适合不想手动遍历流、只想在关键节点打点时替代部分遍历逻辑。下一步完整的MastraModelOutput属性清单见 MastraModelOutput 参考。如果前端使用 AI SDK可以用mastra/ai-sdk的toAISdkStream()把 Mastra 流转成 AI SDK 兼容格式转换器默认 AI SDK v5按你安装的版本传入version例如version: v7再交给useChat()等组件消费。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考