Mastra 客户反馈摘要 Agent 模板：基于 get-feedback 工具与 Observational Memory 构建自学习反馈分析 Agent

Mastra 客户反馈摘要 Agent 模板基于 get-feedback 工具与 Observational Memory 构建自学习反馈分析 Agent【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇指南基于 Mastra monorepo 中的官方模板 template-customer-feedback-summarization 展开你将了解如何一键创建一个能对话式分析客户反馈的 AI Agent掌握get-feedback分页工具的完整参数设计、两个 LLM-as-Judge 质量评分器actionability / completeness的加权打分实现以及通过lastMessages与 Observational Memory 让 Agent 跨会话记住用户偏好、追踪反馈趋势的完整配置方式。模板解决什么问题客户反馈散落在支持工单、应用商店评论、问卷、社交媒体等多个渠道人工汇总费时且难以跟踪趋势。该模板提供了一个名为 Customer Feedback Summarizer 的 AI Agent检索反馈通过get-feedback工具按来源、客户层级、日期范围过滤并支持分页批量拉取分类与评估Agent 自行阅读每一条反馈按类型bug、feature request、praise、complaint、question、情感与紧急度归类识别主题生成高管级报告输出包含 Overview、Key Findings、Critical Issues、Recommendations 四个板块的结构化摘要跨会话记忆借助 Observational Memory 追踪历史分析中形成的模式识别随时间变化的趋势并适应用户展现出的偏好。模板定位是可对话的分析——你可以问它总结所有客户反馈、企业客户的严重问题有哪些、对比本月与上月的主题也可以在聊天中直接粘贴新反馈让它纳入分析。由于 Agent 在会话间保留上下文它会随着使用越来越贴合你的需求。快速开始环境要求Node.js 22.13.0见 package.json 中engines字段推荐使用packageManager指定的 pnpm。npx create-mastralatest --template customer-feedback-summarization cd customer-feedback-summarization创建.env文件OPENAI_API_KEYyour-api-key启动开发服务器npm run devdev脚本实际执行mastra dev会启动 Mastra Studio默认地址为http://localhost:4111。仓库中另有buildmastra build与startmastra start两个脚本用于生产构建与运行。项目结构整个模板代码量很小核心全部位于src/mastra/下templates/template-customer-feedback-summarization/ ├── src/mastra/ │ ├── index.ts # Mastra 实例Agent、存储、日志、可观测性装配 │ ├── agents/ │ │ └── feedback-summarizer.ts # Agent 定义模型、工具、评分器、记忆、指令 │ ├── tools/ │ │ └── get-feedback.ts # get-feedback 工具过滤 分页 │ ├── scorers/ │ │ └── feedback-scorers.ts # actionability / completeness 两个评分器 │ └── data/ │ └── feedback.ts # 75 条静态示例反馈数据 ├── package.json └── tsconfig.json依赖方面模板只引入了 Mastra 生态的核心包mastra/core、mastra/evals、mastra/libsql、mastra/loggers、mastra/memory、mastra/observability外加zod做 schema 校验。核心 Agentfeedback-summarizerAgent 定义在 feedback-summarizer.ts这是整个模板的心脏。完整配置如下节选关键部分export const feedbackSummarizer new Agent({ id: feedbackSummarizer, name: Customer Feedback Summarizer, description: Analyzes and summarizes customer feedback to produce actionable insights..., model: openai/gpt-5.2, tools: { getFeedbackTool }, scorers: { actionabilityScorer: { scorer: actionabilityScorer, sampling: { type: ratio, rate: 1 }, }, completenessScorer: { scorer: completenessScorer, sampling: { type: ratio, rate: 1 }, }, }, memory: new Memory({ options: { lastMessages: 20, observationalMemory: { model: openai/gpt-5-mini, }, }, }), instructions: You are an expert customer feedback analyst. ..., });几个值得关注的配置点双模型策略主 Agent 使用openai/gpt-5.2负责分析而 Observational Memory 的观察提取使用更轻量的openai/gpt-5-mini——把记住偏好这类后台任务交给便宜模型控制成本lastMessages: 20控制每轮注入上下文的最近消息数量即会话内记忆的深度sampling: { type: ratio, rate: 1 }两个评分器以 100% 的采样率对每次运行打分保证输出质量可被持续度量生产环境可调低采样率memory与storage的关联Agent 配置了 Memory 后需要实例级存储来持久化消息与观察记录——这正是 index.ts 中LibSQLStore的职责。instructions一份反馈分析师工作手册该模板的instructions并不是一句简单的角色描述而是一份完整的工作规范值得逐段学习。它规定工作流程被要求总结或分析反馈时调用getFeedbackTool取数。工具是分页的——检查返回的has_more必要时继续翻页覆盖完整数据集亲自通读反馈逐条分类bug、feature request、praise、complaint、question评估情感与紧急度提炼主题综合成一份清晰、可执行的摘要。输出格式四段式Overview反馈总数、日期范围、覆盖的来源、整体情感分布Key Findings按频次和紧急度排序的前 3–5 个主题每个主题说明客户在说什么、影响面多大、情感倾向如何Critical Issues高/严重紧急度的条目按客户层级enterprise pro free和严重度排优先级Recommendations具体、可执行的动作按预期影响排序且每条建议都要回指到具体的反馈数据。跨会话观察的使用方式当存在过往分析产生的观察记录时Agent 被要求将当前发现与历史模式对比例如账单投诉较上一批增多、追踪旧问题是否已解决或复发、适应用户展现的格式偏好并主动指出趋势。语气规范要求直接、数据驱动用数字和百分比明确禁止企业黑话——指令里给出的正反例很典型应说 checkout is broken for 20% of enterprise users而非 there are some opportunities in the checkout experience引用反馈时选最具代表性的例子而不是最戏剧化的企业客户的严重 bug 权重高于免费用户的功能建议。此外指令还覆盖了用户在聊天中直接粘贴新反馈的场景将其放入既有分析上下文中处理并与已有模式和趋势做对比。get-feedback 工具过滤、分页与输出契约工具实现位于 get-feedback.ts使用mastra/core/tools的createTool定义。它的描述本身就是一份使用说明书Retrieves customer feedback from the database. Can filter by source, customer tier, or date range. Supports pagination via limit and offset. Use these to batch through large result sets without overwhelming the context window.输入参数参数类型默认值说明sourceenum无按来源过滤可选support_ticket/app_review/survey/social_mediacustomer_tierenum无按客户层级过滤可选free/pro/enterprisestart_datestring无起始日期YYYY-MM-DD含当日end_datestring无截止日期YYYY-MM-DD含当日limitnumber40单页最大返回条数offsetnumber0跳过的条数用于翻页输出契约outputSchema定义了结构化的分页元数据feedback本页的反馈条目数组每条含id、text、source、date、customer_tiertotal过滤后分页前的匹配总数returned本页实际返回条数limit/offset当前分页参数回显has_more是否还有后续页——Agent 正是靠这个字段决定要不要继续翻页filters_applied以{key: value}形式回显实际生效的过滤条件便于 Agent 在摘要中说明数据口径。分页实现execute逻辑非常直白这也是该工具可直接映射到真实数据库的关键execute: async input { let filtered [...feedbackData]; const filtersApplied: Recordstring, string {}; if (input.source) { filtered filtered.filter(item item.source input.source); filtersApplied.source input.source; } if (input.customer_tier) { filtered filtered.filter(item item.customer_tier input.customer_tier); filtersApplied.customer_tier input.customer_tier; } if (input.start_date) { filtered filtered.filter(item item.date input.start_date!); filtersApplied.start_date input.start_date; } if (input.end_date) { filtered filtered.filter(item item.date input.end_date!); filtersApplied.end_date input.end_date; } const total filtered.length; const limit input.limit ?? 40; const offset input.offset ?? 0; const page filtered.slice(offset, offset limit); return { feedback: page, total, returned: page.length, limit, offset, has_more: offset limit total, filters_applied: filtersApplied, }; }四个过滤条件各自独立、可任意组合AND 语义日期比较直接利用YYYY-MM-DD字符串的字典序等价于时间序的特性has_more由offset limit total判定。当前数据来自静态 fixture见下节把这段filterslice换成WHERELIMIT/OFFSET查询即可接入真实数据源。静态示例数据示例数据定义在 feedback.tsFeedbackItem接口约束了source与customer_tier为联合类型feedbackData数组包含 75 条覆盖 2025-10-02 至 2025-12-15 的模拟反馈内容刻意分布了 bug、计费投诉、功能请求、正面评价等多样类型且企业级客户占比高——正好用于演示enterprise pro free的优先级策略。文件头部的注释也明示真实应用中这些数据应来自数据库、API 或文件上传。质量评分器让写得可执行可度量feedback-scorers.ts 定义了两个评分器在 Agent 中注册后每次运行都会自动评估输出质量。actionabilityScorer可执行性评分该评分器回答一个问题这份摘要是否给出了产品团队能立刻执行的具体建议而不只是模糊观察它基于mastra/core/evals的createScorer以链式 API 组装分为三步preprocess用getAssistantMessageFromRunOutput从运行输出中提取 assistant 文本得到assistantTextanalyze由 judge 模型openai/gpt-5.2按outputSchema输出结构化分析结果包含五个维度——hasRecommendations是否存在建议板块recommendationCount建议条数areSpecific建议是具体如修复使用折扣码时的结账崩溃还是含糊如改进结账体验arePrioritized建议是否按优先级/影响排序tiedToFeedback建议是否回指具体反馈数据confidence0–1 的置信度用于缩放最终得分。generateScore加权求和权重设计体现了具体性最值钱的评价观条件得分存在建议基础分0.2建议数 ≥ 30.21–2 条则 0.1建议具体最重要项0.3建议有优先级0.15建议回指反馈数据0.15最终分数为min(加权总分 × confidence, 1)若完全没有建议板块则直接记 0 分。generateReason步骤还会把上述各维度拼成人类可读的评语如 Found 4 recommendation(s). Recommendations are specific and actionable.方便在 Studio 中查看评分依据。completenessScorer完整性评分第二个评分器一行搞定export const completenessScorer createCompletenessScorer();它直接复用mastra/evals/scorers/prebuilt的内置完整性评分器评估 Agent 的摘要是否覆盖了输入的全部反馈条目而没有遗漏——这与可执行性互补一个管说得有用一个管看得全面。两个评分器同时挂在 Agent100% 采样与 Mastra 实例上形成对该模板输出质量的双重自动度量。实例装配存储、日志与可观测性index.ts 展示了把 Agent 跑起来的完整骨架export const mastra new Mastra({ agents: { feedbackSummarizer }, scorers: { actionabilityScorer, completenessScorer }, storage: new LibSQLStore({ id: mastra-storage, url: file:./mastra.db, }), logger: new PinoLogger({ name: Mastra, level: info }), observability: new Observability({ configs: { default: { serviceName: mastra, exporters: [new MastraStorageExporter(), new MastraPlatformExporter()], spanOutputProcessors: [new SensitiveDataFilter()], }, }, }), });各部分的作用LibSQLStore以本地文件file:./mastra.db为存储后端持久化会话消息与 Observational Memory 的观察记录——没有它lastMessages跨请求的历史和跨会话追踪趋势都无法成立PinoLogger以info级别输出运行日志Observability通过MastraStorageExporter与MastraPlatformExporter导出追踪数据并用SensitiveDataFilter处理 span 输出中的敏感信息保证分析链路可观测且不泄露反馈原文中的隐私片段。Observational Memory跨会话的学习机制README 强调的核心卖点——agent remembers context across sessions, so it gets more useful over time——由 Agent 上的这段 Memory 配置驱动memory: new Memory({ options: { lastMessages: 20, observationalMemory: { model: openai/gpt-5-mini, }, }, });两者的分工不同lastMessages: 20是会话内机制每次运行时把该线程最近 20 条消息注入上下文解决本次对话记得住的问题observationalMemory是跨会话机制由独立的轻量模型此处为gpt-5-mini从对话中提取观察——用户偏好、反复出现的主题、历史结论等——持久化到存储中供后续会话读取。结合 instructions 中Working with observations from past sessions一节Agent 被要求拿这些观察去对比历史模式、追踪问题是否复发、主动指出趋势。从 monorepo 的mastra/memory源码看Observational Memory 以处理器processor形式挂接在消息流上围绕线程thread维度管理观察记录并通过专门的激活与缓冲机制决定何时触发观察提取参见 observational-memory 处理器实现 及其配套测试。模板层面你只需给出一个模型配置其余生命周期由框架托管——这正是配置一行、能力跨会话的用法。配合实例级的LibSQLStore观察记录得以落盘同一个 Studio 用户即同一 thread 归属多次提问总结反馈时Agent 便能说出账单类投诉较上一批增多这类带时间维度的结论而不是每次都从零开始。使用方式与真实数据接入在 Studio 中交互打开 Studio导航到 Customer Feedback Summarizer Agent尝试如下提问README 推荐的问题模式均可触发get-feedback工具带过滤条件的调用Summarize all customer feedback全量总结What are the critical issues from enterprise customers?按customer_tier: enterprise过滤Show me only the feature requests from pro users按层级 类型筛选Compare support tickets to app reviews按source分组对比Agent 会用get-feedback工具取数自动翻页逐条分析后生成带 findings 与 recommendations 的结构化摘要直接把新反馈粘贴进聊天Agent 会将其纳入既有分析并与已有趋势对比跨会话时Observational Memory 持续记录模式支撑趋势类问题。README 还指出该 Agent 演示运行在 Mastra Studio 中但也可以把 Agent 接入自建的 React、Next.js 或 Vue 应用——官方文档提供了 Mastra Client SDK 以及 AI SDK UI、CopilotKit、Assistant UI 等 agentic UI 库的接入路径。接入真实数据源get-feedback工具当前读取的是静态 fixture。要接入真实数据按 README 的指引只需更新 get-feedback.ts 中的execute函数把内存过滤替换为数据库或 API 查询source/customer_tier过滤 → SQL 的WHERE条件start_date/end_date→ 日期范围查询limit/offset→LIMIT/OFFET分页has_more、total等输出字段保持不变Agent 侧的翻页逻辑与 instructions 完全无需改动。工具描述中刻意保留的limit、offset、has_more分页接口就是为这种映射设计的——这也是该模板接口先行、数据后接的设计思路先让 Agent 学会分批取数、控制上下文窗口再无缝替换底层数据源。小结与参考路径这个模板用不到 5 个源文件演示了一条完整的 Mastra Agent 工程化路径Agent模型 工具 评分器 记忆→createTool带分页契约的取数工具→createScorer可执行的加权 LLM 评分→Mastra实例存储 日志 可观测性→Memory会话内 跨会话两层记忆。值得直接复用与仿写的要点用一份结构化的instructions流程、输出格式、语气规范、跨会话观察用法约束 Agent 行为而非只给一句角色设定工具的输出 schema 显式返回分页元数据total/has_more/filters_applied把翻不翻页的决策依据交给 Agent用双评分器可执行性 完整性以 100% 采样率自动度量输出质量权重向具体性倾斜主分析模型与观察提取模型分档配置兼顾质量与成本。主要参考文件模板 READMEAgent 定义get-feedback 工具示例反馈数据评分器实现Mastra 实例装配依赖与脚本Observational Memory 处理器【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考