智能体:会调用你的 API 的 AI

有些问题需要的查询无法事先规划。为工作流添加工具:也就是你自己的端点,每个都有名称和 Schema。由模型决定调用哪个,ModelRiver 在你设定的限制内发出带签名的调用,由你的端点决定每个用户能看到什么。你的数据库始终留在你的后端。

智能体如何运行

示例:一位客户询问订单到哪了。模型调用你的订单工具,你的端点核实提问者身份,模型写出答案。

  1. 您的后端

    开始运行

    你的后端调用 POST /v1/ai/async (作用于开启工具的工作流),并说明是谁在提问。你会立即拿到一个通道。

    { messages, "end_user": { "id": "cus_812" } }
  2. ModelRiver

    模型选择工具

    模型读取问题,并请求调用你的某个工具。ModelRiver 会按该工具的 Schema 检查参数。

    get_order { "order_id": "1234" }
  3. 你的端点

    你的端点被调用

    一个带签名的 POST 会带来工具名称、参数,以及你的后端指明的终端用户。模型永远看不到终端用户是谁。

    POST /tools/order { tool, arguments, end_user }
  4. 你的端点

    回传你的数据

    核实提问者身份,查询订单,并在工具超时时间内(默认 10 秒)以 JSON 只返回模型需要的字段。

    { "status": "shipped", "eta": "Thursday" }
  5. ModelRiver

    模型给出答案

    模型读取结果。它可能再调用其他工具,然后写出答案。默认最多 5 个模型轮次和 16 次工具调用。

  6. 你的用户的浏览器

    实时查看

    你的应用会显示正在运行哪个工具,随后完整答案通过 WebSocket 通道送达。

    tool_call_started → response
tools.js
const raw = express.raw({ type: "application/json" });

// Called when the model asks for get_order
app.post("/tools/order", raw, async (req, res) => {
  if (!verified(req)) return res.sendStatus(401);
  const call = JSON.parse(req.body);

  // Who is asking: end_user, never the model
  const order = await db.orders.find(
    call.arguments.order_id, call.end_user.id);
  if (!order) return res.status(404).json({
    error: { message: "No such order" } });

  // Return only what the model needs
  res.json({ status: order.status, eta: order.eta });
});

何时使用智能体

适用场景

  • 需要由模型决定查询什么,例如回答开放式问题的助手
  • 你的应用已有 AI 可以复用的端点:订单、账户、报表
  • 一个问题可能需要多次查询,也可能一次都不需要

以下情况请选择其他模式

  • 一次模型调用就够了:使用 同步 or 异步
  • 步骤总是固定不变:用 后端管道 按固定顺序运行它们
  • 答案必须逐个 token 流式输出:目前智能体会一次性送达完整答案

ModelRiver 为你处理的部分

5 个轮次

每请求

一个请求中的模型调用次数,可设为 2 到 10。工具调用次数也有上限,默认 16 次。

先征得同意

会更改内容的工具

会取消、发送或预订的工具,只有在终端用户批准这次调用后才会运行。它只发送一次,绝不重试。

已签名

每一次工具调用

每次调用都带有签名(HMAC-SHA256),并指明你的后端发送的终端用户,因此由你的端点决定该用户能看到什么。

已记录

每一轮

每个模型轮次和工具调用都会显示在请求日志中,并附有耗时和状态。

给你的第一个工作流加一个工具