rungent核心概念
工作原理
rungent 由哪些部分组成、运行时跑在哪里、一次请求经过哪些步骤、界面说的是什么协议,以及这些文档使用的术语。
你要安装什么#
rungent 是一个运行时,用 TypeScript 写成,只依赖 Web 标准 API。它以一个 npm 包 rungent 发布,入口按你的技术栈需要导入:
| 导入 | 是什么 |
|---|---|
rungent |
运行时:createRungent 和各种存储 |
rungent/react |
面板、⌘K 命令面板、确认卡、表单、模型设置 |
rungent/client |
HTTP API 的类型化客户端,把事件归约成一个对话线程 |
rungent/delegation |
签名密钥,以及你的 API 要做的断言检查 |
rungent/knowledge |
把你的文档变成可引用的搜索来源 |
rungent/sql/postgres、/sql/sqlite、/sql/d1 |
存储和知识用的数据库驱动 |
rungent/node |
适配 Node (req, res) 的 nodeHandler,以及 rungent serve 背后的服务 |
rungent/cli |
作为库的 CLI,用来做品牌 CLI |
rungent/protocol、/catalog、/search、/documents |
契约的类型和辅助函数,供你自己的工具使用 |
这个包只有一个命令 rungent:它是每个 rungent 宿主的 CLI,也是编写工具(check、keys、brand),还有 rungent serve。另有两样不在 npm 上:运行 rungent serve 的 Docker 镜像 ghcr.io/rungent/rungent-server,以及 PyPI 上的 Python kit rungent(导入名 rungent)。
运行时跑在哪里#
- 内嵌
- 你的 JavaScript APIHono、Express、Workers、Node
- rungent 在同一进程一个 fetch 处理函数
- 在你的 API 旁边
- 两种方式都
- 同源用户的 Cookie 直接可用
- 同一份契约输入 OpenAPI,输出断言
两种形态都在你自己的域名下提供同样的路径:助手用的 /rungent/v0/*、/mcp、/skill.md、/llms.txt 和 /.well-known/rungent-keys.json。你的 Web 应用以同源请求访问它们,所以用户现有的登录会话就是凭据。JavaScript 内嵌 rungent;Python 与其他技术栈在你的 API 旁边运行它。
一次请求,一步一步#
用户发出一条消息后,rungent 依次执行这些步骤。每一步都写在代码里,而不是提示词里。
- 目录rungent 用用户的凭据读取你的 OpenAPI,只保留带 x-rungent 且该用户可见的操作。
- 预检索如果你把文档交给了 rungent,它先按用户的话检索一遍。
- 路由创建或修改的请求直接送到对应的操作。
- 表单操作的表单打开并预填;在你的应用里,就是页面自己的表单。
- 解析用户写的名称(「train-01」)通过你的列表操作换成 ID。
- 确认写操作显示一张写明对象和变更的卡片;确认绑定到这组确切的参数。
- 调用rungent 带着用户凭据和签名断言调用你的 API,由你授权。
- 流式文字、工具活动和结果以事件流回界面,断线后可以续上。
提问走短路径:Agent 用你的读操作和搜索查找信息,然后带引用作答。除非你另行设置,读操作从不需要确认。
以用户身份调用#
rungent 在你的产品里没有账号。每次调用都带着用户自己的凭据,所以你的权限检查原样生效;还带着一个 Rungent-Assertion:一份签名令牌,写明用户、操作、确切的请求和确认。你的 API 用 rungent 的公钥校验它。详见以用户身份调用。
协议#
助手通过 HTTP 和 server-sent events 说 AG-UI。rungent 在上面加了一层小小的约定:每个事件带一个序号,客户端重连时正好拿到错过的那些;另有四种暂停,每种都由用户来答复:
| 暂停 | 何时 | 用户如何答复 |
|---|---|---|
| 确认 | 写操作之前 | 确认或拒绝 |
| 表单 | 带表单的操作之前 | 操作的完整参数 |
| 提问 | Agent 问是哪个对象或哪个动作 | 一个选项 |
| 任务 | 你的 API 稍后执行这项工作 | 无需答复;由你的 API 回报结果 |
任何 AG-UI 客户端都能驱动 rungent,React 面板只是其中之一。见 HTTP API。
rungent 有什么不同#
Agent 框架(LangGraph、Mastra、Vercel AI SDK)给你一个循环,工具、身份和界面都留给你自己做。OpenAPI 生成器(Stainless、Speakeasy)给开发者生成 SDK 和 MCP 服务,用开发者自己的密钥调用你的 API。rungent 从你已有的 API 出发,在你的产品里为当前登录用户运行 Agent,用你的表单,并在代码里强制确认。它也能和它们配合:一个耗时很长的 LangGraph 工作流,可以做成一个以延后任务作答的操作。
这些文档使用的术语#
| 词 | 含义 |
|---|---|
| 宿主 | 你的产品,即 rungent 调用其 API 的那个服务 |
| 目录 | 你的 OpenAPI 中带 x-rungent 的操作,按某个用户可见的范围 |
| 操作 | 目录中的一个 HTTP 端点;对 Agent、MCP 和 CLI 来说是一个工具 |
| 效果 | 操作做什么:读取、创建、修改、删除,或对外动作 |
| 写操作 | 效果不是 read 的任何操作 |
| 入口 | 操作出现的地方:助手、MCP、CLI |
| 身份 | 说明某个凭据属于谁的那一个操作 |
| 断言 | rungent 代表用户发出的每次调用上的签名令牌 |
| 表单 | 操作运行前向用户收集的输入 |
| 路由 | 把修改请求送到对应表单的那一步 |
| 中断 | 一次运行中等待用户的暂停:确认、表单、提问或任务 |
| 面板 | 你页面旁的助手面板,来自 rungent/react |
供 Agent 读取: how-it-works.md编辑此页