手写一次循环以后，框架的作用会具体很多。模型接入、工具消息、流式返回和状态保存都需要维护。业务增加以后，把这些通用部分反复写一遍，会占掉不少时间。

选框架可以从当前缺口出发。知识库助手眼下需要的是接入模型、定义检索工具，以及把答案和引用返回给页面。先把这条路径跑通，再看恢复执行或复杂分支是否真的需要加入。

几个名字各自负责什么

原教程同时介绍了 Mastra 和 LangChain.js。Mastra 把 Agent、Workflow、Memory 和调试能力放在同一套 TypeScript 开发体验中。LangChain 提供模型、工具和 Agent 的组合接口，需要更细的状态控制时可以继续使用 LangGraph。追踪和评估则可以放到 LangSmith 一类工具里。这些职责可以从 Mastra 文档 与 LangChain 文档 中核对。

选择时最好拿自己的任务试一遍。能否连接当前使用的模型，部署环境是否支持依赖，工具失败后在哪里能看见结果，这些问题会比下载量更早影响项目。

前端交互占主要工作时，也可以评估 AI SDK 的模型与消息流能力。已有后端则先检查能否直接嵌入。为了一个小型问答功能另起完整服务，会增加部署和维护工作。

用 Mastra 理解 Agent 与 Workflow

原教程创建 Agent 时，先设置稳定标识、展示名称、行为指令和模型，再挂上工具与记忆。这里可以沿用普通模块的理解方式，先定义对象，再注册到应用入口。

开放任务由 Agent 依据结果选择行动。必须按规则经过的步骤，可以交给 Workflow。

例如生成文章以后再翻译，流程里可以有两个 Step。第一步接收主题，返回 { article }；第二步接收文章，返回 { translated }。一次实际执行就是一个 Run。

这几个对象要靠真实字段接起来。如果整个工作流声明返回 { result }，最后一步却只交回 { translated }，就需要统一名称或显式映射。schema 可以描述契约，实际输出还得遵守契约。

知识库助手也可以设计成两个固定步骤。先检索并生成答案，再检查引用 ID 是否来自本次结果。检查不通过时，返回明确错误或者重新生成。至于要不要允许再次检索，需要在流程里规定。

组合组件之前，先看数据形状

LangChain 的 Runnable 接口让组件能以相近方式调用。模型、模板和解析器因此更容易组合。它们的输入输出类型仍可能不同。

原教程中一个容易忽略的情况，是上一步已经返回字符串，下一步模板却需要 { translated }。中间需要映射。

// 自定义映射示意，展示字段怎样接上
const translated = "translated text";
const nextInput = { translated };

同样的问题会出现在检索和生成之间。检索器可能返回 Document 数组，生成模板需要整理好的资料文本。程序应该明确选择哪些字段参与上下文，哪些字段保留给引用显示。

每个步骤先打印一次输入类型和输出结构，通常就能发现字段接错。等流程稳定以后，再用适当的日志记录这些信息。真实用户资料和凭证应当脱敏，避免调试输出变成额外的数据副本。

调试界面能帮你确认到哪一步

Studio 或调用追踪能回答一类很有价值的问题。工具究竟返回了错误数据，还是模型没有正确使用它？

如果检索工具已经拿错片段，就先修检索；如果片段正确，答案却遗漏条件，再看上下文和生成阶段。把一次运行展开，比只看最终那句话更容易找到修改位置。

开发调试界面与产品页面承担不同任务。工具在 Studio 中能运行以后，还需要自己的接口、用户状态、错误展示和部署配置。到这一阶段，框架示例只能证明部分能力已经连通。

具体 API 会随版本变化。这篇用职责和数据契约解释框架，不把结构示意当作可直接复制的安装模板。真正练习时，固定一组依赖，保留锁文件，再按对应版本文档补齐调用。

试着用你选的一套框架重做上一篇的文件读取工具。记录哪些循环代码被框架接管，哪些权限判断仍由自己维护。能把这两部分指清楚，框架就已经帮上忙了。

延伸阅读

本篇依据冴羽《AI Agent 开发实战》学习整理稿中的框架、Mastra 工作流与 Runnable 章节重写。原教程见 框架选型、Mastra 入门、LangChain.js 入门 和 LangChain.js 核心概念。

上一篇 · 系列目录 · 下一篇