Rivet：可视化LLM Agent构建工具

为什么需要 Rivet：多步骤 LLM 流程看不清、改不动

传统的 LLM Agent 开发方式是用代码逐行编排：用户输入 → 意图识别 → 向量检索 → Prompt 组装 → 模型生成 → 工具调用 → 结果汇总。每一环都是一次 LLM 调用或数据处理，代码里夹杂着大量 prompt 字符串、条件分支和调试日志。这类实现的痛点很具体：业务流程与代码结构强耦合，改一个 prompt 措辞需要定位到对应代码位置并重新构建部署；产品经理和运营无法参与流程调试；运行时的中间状态（检索到了什么、模型实际收到了什么）难以可视化复查，出了问题只能靠翻日志。

Rivet 把流程拆解为可视化节点图：每个节点是一个可复用的数据操作单元，包括 LLM 调用、Prompt 模板、文档检索、HTTP 请求、条件分支等，节点之间的连线定义数据流向。开发者在图中直接看到每个节点的输入输出结构，修改 Prompt 在节点面板内完成，不需要改动宿主代码。更关键的是，图以 JSON 格式保存，可通过 npm 包在 Node.js 或 React 应用中加载执行，实现“编辑时可视化、运行时程序化”的共存模式——Rivet 不取代你的代码工程，而是把流程设计和实验环节从代码中抽离出来。

与同类工具相比，Rivet 的气质明显偏向开发者：它提供类型化的数据槽与编辑期静态检查，错误在保存图时就被捕获而非运行时才暴露；同时支持将图嵌入到生产应用中，在真实运行环境里继续调整和观察流程。这种“图与代码可拆分、可合并”的设计，是它区别于纯拖拽配置平台的核心差异。

安装与环境配置：3 步就绪

第一步：安装桌面编辑器（可选）。 到官网下载 macOS 或 Windows 安装包。编辑器用于创建和调试 .rivet 图文件；如果只需要在代码中运行别人已编辑好的图，可以跳过这一步。

第二步：在现有 Node.js 项目中安装运行时包。 Rivet 的核心运行时拆分为多个 npm 包，按需安装：

第三步：验证安装。 在项目根目录创建一个最小测试脚本，确认包能正常加载并输出版本信息：

test-rivet.mjs 内容如下：

如果控制台输出图运行的 JSON 结果，说明环境配置完成。

# 核心库（一般由其他包间接依赖，无需手动安装）npm install @ironclad/rivet-core # Node.js 环境中加载并运行图文件npm install @ironclad/rivet-node # React 应用中渲染可交互的运行时界面npm install @ironclad/rivet-react # CLI 工具（校验、运行图文件）npm install -g @ironclad/rivet-cli

# 验证 CLI 可用rivet --version # 验证 Node 包可加载（先创建一个 test-rivet.mjs）node test-rivet.mjs

import { loadGraphFromFile } from '@ironclad/rivet-node'; const graph = await loadGraphFromFile('./hello.rivet');const result = await graph.run({ question: '你好' });console.log(JSON.stringify(result));

快速上手：10 分钟跑通第一个 Graph

核心思路是“先在可视化编辑器中创建图，再在代码中调用它”。以构建一个最简问答 Graph 为例：

1. 打开 Rivet 桌面编辑器，新建一个空白工程。

2. 在节点面板中搜索并添加一个 Graph Input 节点，在属性中定义输入参数，例如 question（字符串类型），作为整个图的外部入口。

3. 添加一个 Prompt Template 节点，在模板编辑器中写入 你是 AI 助手，请回答：{{question}}，并把 Graph Input 的 question 变量拖入模板。

4. 添加一个 LLM 节点（如 OpenAI 模型），在配置面板填入模型名称与 API Key（环境变量方式），将 Prompt Template 的输出连接到 LLM 的输入。

5. 添加 Graph Output 节点，连接 LLM 的输出，定义输出字段 answer。

6. 点击编辑器中的运行按钮，在下方调试面板查看 answer 的实际输出，确认 Prompt 与模型调用链路正常。

7. 保存文件为 hello.rivet。

回到项目中，运行前面创建的 test-rivet.mjs，即可在代码里拿到图中的运行结果。进阶技巧：graph.run() 方法除了传输入参数外，还支持传入处理函数（如工具调用节点的回调处理器），可以在运行时把外部系统的数据注入图中，实现 Agent 式循环。

核心能力详解：4 大支柱

支柱一：蓝图式节点图编辑器。 Rivet 的编排范式借鉴自游戏引擎蓝图系统，节点分为数据处理节点（LLM、Prompt 模板、Embedding、文本处理、HTTP 请求等）与控制流节点（条件分支、循环、映射等）。所有节点的输入输出槽都有类型（string、number、object 等），连线必须类型匹配，保存图时执行静态类型检查，错误在编辑期即被拦截，而不是等到生产运行才崩溃。

支柱二：Prompt 可视化模板。 Prompt 节点内置专门的模板编辑器，支持把图中其他节点的输出变量直接插入模板文本，并支持配置少量示例（few-shot）辅助模型理解。模板渲染逻辑位于核心包内，不依赖第三方模板引擎，且避免了 prompt 字符串散落在各业务代码文件中的维护难题。

支柱三：运行时交互式 Canvas（Runtime Canvas）。 这是 Rivet 区别于多数编排工具的独有能力。当应用通过 @ironclad/rivet-react 嵌入图时，业务人员可以在真实运行环境中看到图的状态：哪些节点已执行、每个节点的输出值是什么；还可以直接修改节点参数并触发重新运行。这把调试能力从开发环境延伸到生产应用内部，对产品、运营协作定位问题非常有效。

支柱四：以代码为中心的图生命周期管理。 .rivet 文件本质是结构化 JSON，包含节点定义、连线和 schema 版本号，天然适合提交进 Git 做代码评审和版本回溯。官方 CLI 提供 rivet run 运行图、rivet graph validate 校验图结构，可在 CI 流程中作为前置卡点。由于数据流在加载时被静态解析，图运行过程是确定的（模型本身的随机性除外），便于测试与复现。

生产部署与监控：从上线到运维

部署方式一：图嵌入 Node.js 服务。 将 .rivet 文件作为静态资源随应用打包，服务启动时调用 loadGraphFromFile 加载图，请求处理时通过 graph.run(input) 执行。适合构建带 RAG 或 Agent 能力的后端 API：图的迭代只需替换 .rivet 文件并重启服务，业务代码无需改动。

部署方式二：图嵌入 React 前端。 使用 @ironclad/rivet-react 完成两件事：一是把图正常跑在浏览器侧（纯前端 Agent 场景），二是在管理后台渲染运行时 Canvas，让运营人员直接看到每个对话步骤的节点状态、检索结果和模型输出，并在界面上调整参数后重放流程。

可观测性。 graph.run() 返回 Promise，resolve 后拿到完整的图输出对象；对每个节点的耗时与调用记录，需在应用侧接入日志框架统一采集。建议在 CI 中加入 rivet graph validate 校验，防止图文件结构错误进入生产；对包含 HTTP 或数据库写入的图，要重点设计幂等逻辑，避免图重跑时产生重复副作用。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>坑 1：把 Rivet 当成无代码平台。图本身不具备运行能力，纯编辑器内的 Run 只用于开发调试，生产环境必须通过 npm 包把图嵌入工程代码，团队中至少要保留一名工程师负责运行时集成。</li><li>坑 2：误以为在运行时 Canvas 上改值会立即生效。Rivet 的数据流在加载时静态分析，修改节点值后必须触发重新运行（rerun）才会按新值执行，它不是实时热更新机制。</li><li>坑 3：跨大版本直接导入 .rivet 文件。图文件内包含 schema 版本信息，2.x 与早期 alpha 版本的图不保证兼容，多人协作时应锁定一致的编辑器版本与 npm 包版本。</li><li>坑 4：对外部副作用节点不做幂等设计。包含 HTTP 请求、数据库写入的节点在每次重跑时都会再次执行，测试和生产重放前需确认外部系统可承受重复调用。</li><li>坑 5：把 API Key 存进图文件。图文件是明文 JSON 且会进 Git，密钥应通过运行环境注入，编辑器本地配置不要随工程分发。</li></ul>

版本迭代

Rivet 源自游戏开发领域的可视化脚本经验，最初面向游戏叙事创作场景，2023 年开源后转向通用 LLM 应用编排；2024 年经历 2.x 架构重写，强化了数据流引擎、TypeScript 类型化节点槽与运行时嵌入能力，逐步形成“图即代码资产”的工程化定位。（截至训练数据，可能已有更新版本）

AI 应用场景

常见误区

面试题