rungent v0.5.1
EN中文

rungent核心概念

工作原理

rungent 由哪些部分组成、运行时跑在哪里、一次请求经过哪些步骤、界面说的是什么协议,以及这些文档使用的术语。

人和 Agent 在这里工作产品内助手页面旁的助手面板⌘K 搜索资源与文档MCP 客户端Claude Code、Cursor 等CLI你的品牌命令skill.md · llms.txt给任何 Agentrungent一份目录你的 OpenAPI,按用户可见路由 → 表单 → 确认每次变更同一条路径Agent 循环模型链、重试、上限会话与流式AG-UI 事件,可续传搜索与知识联邦检索,带引用你的产品HTTP APIOpenAPI 3.1 + x-rungent身份当前登录的是谁权限由你的规则决定页面表单与业务页面同一张表单文档回答引用它们用户自己的会话用户凭据+ 签名断言结果,你的报错每次调用都以当前登录用户的身份执行,rungent 没有自己的权限。人和 Agent 在这里工作产品内助手页面旁的助手面板⌘K 搜索资源与文档MCP 客户端Claude Code、Cursor 等CLI你的品牌命令skill.md · llms.txt给任何 Agent用户自己的会话rungent一份目录你的 OpenAPI,按用户可见路由 → 表单 → 确认每次变更同一条路径Agent 循环模型链、重试、上限会话与流式AG-UI 事件,可续传搜索与知识联邦检索,带引用用户凭据+ 签名断言你的产品HTTP APIOpenAPI 3.1 + x-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)。

运行时跑在哪里#

  1. 内嵌
    • 你的 JavaScript APIHono、Express、Workers、Node
    • rungent 在同一进程一个 fetch 处理函数
  2. 在你的 API 旁边
    • 你的 APIPython、Go、Java 等
    • 旁边运行 rungent serve由代理转发 /rungent 和 /mcp
  3. 两种方式都
    • 同源用户的 Cookie 直接可用
    • 同一份契约输入 OpenAPI,输出断言

两种形态都在你自己的域名下提供同样的路径:助手用的 /rungent/v0/*、/mcp、/skill.md、/llms.txt 和 /.well-known/rungent-keys.json。你的 Web 应用以同源请求访问它们,所以用户现有的登录会话就是凭据。JavaScript 内嵌 rungent;Python 与其他技术栈在你的 API 旁边运行它。

一次请求,一步一步#

用户发出一条消息后,rungent 依次执行这些步骤。每一步都写在代码里,而不是提示词里。

  1. 目录rungent 用用户的凭据读取你的 OpenAPI,只保留带 x-rungent 且该用户可见的操作。
  2. 预检索如果你把文档交给了 rungent,它先按用户的话检索一遍。
  3. 路由创建或修改的请求直接送到对应的操作。
  4. 表单操作的表单打开并预填;在你的应用里,就是页面自己的表单。
  5. 解析用户写的名称(「train-01」)通过你的列表操作换成 ID。
  6. 确认写操作显示一张写明对象和变更的卡片;确认绑定到这组确切的参数。
  7. 调用rungent 带着用户凭据和签名断言调用你的 API,由你授权。
  8. 流式文字、工具活动和结果以事件流回界面,断线后可以续上。

提问走短路径: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编辑此页