四种模式
同步
最简单你的服务器发送请求,并在同一次调用中拿到完整的 AI 结果。
POST /v1/ai查看工作原理 →异步
实时送达用户立即拿到一个通道。结果会实时推送给你的用户,并送达你的 webhook。
POST /v1/ai/async查看工作原理 →后端管道
你的数据参与其中AI 步骤与你的后端轮流执行。当某一步需要你的数据时,ModelRiver 会调用你。
POST /v1/ai/async + backend steps查看工作原理 →智能体
AI 调用你的 API由模型决定调用你的哪些工具。每个工具都是你自己的一个端点,ModelRiver 负责发出带签名的调用。
POST /v1/ai/async + tools智能体如何运行
示例:一位客户询问订单到哪了。模型调用你的订单工具,你的端点核实提问者身份,模型写出答案。
- 您的后端
开始运行
你的后端调用
{ messages, "end_user": { "id": "cus_812" } }POST /v1/ai/async(作用于开启工具的工作流),并说明是谁在提问。你会立即拿到一个通道。 - ModelRiver
模型选择工具
模型读取问题,并请求调用你的某个工具。ModelRiver 会按该工具的 Schema 检查参数。
get_order { "order_id": "1234" } - 你的端点
你的端点被调用
一个带签名的 POST 会带来工具名称、参数,以及你的后端指明的终端用户。模型永远看不到终端用户是谁。
POST /tools/order { tool, arguments, end_user } - 你的端点
回传你的数据
核实提问者身份,查询订单,并在工具超时时间内(默认 10 秒)以 JSON 只返回模型需要的字段。
{ "status": "shipped", "eta": "Thursday" } - ModelRiver
模型给出答案
模型读取结果。它可能再调用其他工具,然后写出答案。默认最多 5 个模型轮次和 16 次工具调用。
- 你的用户的浏览器
实时查看
你的应用会显示正在运行哪个工具,随后完整答案通过 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 });
});ModelRiver 为你处理的部分
5 个轮次
每请求
一个请求中的模型调用次数,可设为 2 到 10。工具调用次数也有上限,默认 16 次。
先征得同意
会更改内容的工具
会取消、发送或预订的工具,只有在终端用户批准这次调用后才会运行。它只发送一次,绝不重试。
已签名
每一次工具调用
每次调用都带有签名(HMAC-SHA256),并指明你的后端发送的终端用户,因此由你的端点决定该用户能看到什么。
已记录
每一轮
每个模型轮次和工具调用都会显示在请求日志中,并附有耗时和状态。