本指南为一个聊天工作流添加一个工具 get_sales_summary。你需要一个已经能回答普通聊天请求的工作流,并且托管工具已为你的组织启用。
1. 创建签名密钥
在控制台中打开工作流。在 General 选项卡的 Connect your backend 下,选择 Let the AI call my endpoints,然后选择 Tools 选项卡。在工具列表下方的 Tool signing secret 中,选择 Create secret。
密钥以 mrts_ 开头,只显示一次。把它复制到后端的环境变量中,例如命名为 MODELRIVER_TOOL_SECRET。一个密钥覆盖项目中的所有工具。
2. 编写端点
工具就是一个接收签名 POST 并返回 JSON 的 HTTPS 端点。下面这个端点会检查签名,读取请求是为谁发起的,并返回该用户的数据。
Node.js (Express)
1import crypto from 'node:crypto';2import express from 'express';3 4const app = express();5const SECRETS = [process.env.MODELRIVER_TOOL_SECRET];6 7function verifyToolCall(rawBody, headers, secrets, toleranceSeconds = 300) {8 const timestamp = headers['x-modelriver-timestamp'];9 const callId = headers['x-modelriver-tool-call-id'];10 const signatures = String(headers['x-modelriver-signature'] || '')11 .split(',')12 .map((part) => part.trim())13 .filter((part) => part.startsWith('v2='))14 .map((part) => part.slice(3));15 16 if (!/^\d+$/.test(timestamp || '') || !callId || signatures.length === 0) return false;17 if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false;18 19 return secrets.some((secret) => {20 const expected = crypto21 .createHmac('sha256', secret)22 .update(`v2.${timestamp}.${callId}.`)23 .update(rawBody)24 .digest('hex');25 const expectedBytes = Buffer.from(expected);26 27 return signatures.some((given) => {28 const givenBytes = Buffer.from(given);29 return givenBytes.length === expectedBytes.length && crypto.timingSafeEqual(givenBytes, expectedBytes);30 });31 });32}33 34// express.raw keeps the body as the exact bytes ModelRiver signed35app.post('/tools/sales-summary', express.raw({ type: 'application/json' }), async (req, res) => {36 if (!verifyToolCall(req.body, req.headers, SECRETS)) {37 return res.status(401).json({ error: { message: 'Bad signature' } });38 }39 40 const call = JSON.parse(req.body.toString('utf8'));41 42 // Who is asking comes from end_user, which your backend sent and ModelRiver signed.43 // Never take it from call.arguments: the model wrote those.44 const storeId = call.end_user.claims.store_id;45 const period = call.arguments.period ?? 'this_week';46 47 const summary = await db.salesSummary(storeId, period);48 if (!summary) {49 return res.status(404).json({50 error: { message: 'No sales data for that period', user_message: 'There are no sales for that period yet.' },51 });52 }53 54 res.json({ period, revenue: summary.revenue, orders: summary.orders, change_vs_previous: summary.change });55});56 57app.listen(3000);Python (FastAPI)
1import hashlib, hmac, json, os, time2from fastapi import FastAPI, Request3from fastapi.responses import JSONResponse4 5app = FastAPI()6SECRETS = [os.environ["MODELRIVER_TOOL_SECRET"]]7 8def verify_tool_call(raw_body: bytes, headers, secrets, tolerance_seconds: int = 300) -> bool:9 timestamp = headers.get("x-modelriver-timestamp", "")10 call_id = headers.get("x-modelriver-tool-call-id", "")11 signatures = [12 part.strip()[3:]13 for part in headers.get("x-modelriver-signature", "").split(",")14 if part.strip().startswith("v2=")15 ]16 17 if not timestamp.isdigit() or not call_id or not signatures:18 return False19 if abs(time.time() - int(timestamp)) > tolerance_seconds:20 return False21 22 signed = f"v2.{timestamp}.{call_id}.".encode() + raw_body23 for secret in secrets:24 expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()25 if any(hmac.compare_digest(expected, given) for given in signatures):26 return True27 return False28 29@app.post("/tools/sales-summary")30async def sales_summary(request: Request):31 raw_body = await request.body() # the exact bytes ModelRiver signed32 if not verify_tool_call(raw_body, request.headers, SECRETS):33 return JSONResponse({"error": {"message": "Bad signature"}}, status_code=401)34 35 call = json.loads(raw_body)36 37 # Who is asking comes from end_user, never from the arguments.38 store_id = call["end_user"]["claims"]["store_id"]39 period = call["arguments"].get("period", "this_week")40 41 summary = await db.sales_summary(store_id, period)42 if summary is None:43 return JSONResponse(44 {"error": {"message": "No sales data for that period",45 "user_message": "There are no sales for that period yet."}},46 status_code=404,47 )48 49 return {"period": period, "revenue": summary.revenue, "orders": summary.orders,50 "change_vs_previous": summary.change}端点必须能通过 HTTPS 从公网访问。如果端点在你自己的机器上,请参见测试本地端点。
3. 注册工具
在 Tools 选项卡上,选择 Add tool 并填写:
| 字段 | 值 |
|---|---|
| Name | get_sales_summary |
| Description for the model | Returns revenue, order count and the change against the previous period for the signed-in user's store. Use it for any question about how sales are going. |
| Progress label | Reading this week's sales… |
| Endpoint URL | https://api.yourapp.com/tools/sales-summary |
| Timeout | 10(秒) |
| What does calling it do? | Only reads data |
在 Example arguments 中,输入一次调用应携带的参数示例:
1{2 "period": "this_week"3}选择 Build parameters from example。ModelRiver 会根据示例推导出 JSON Schema,并在 Parameters 下列出参数:每个键都会成为必填参数,其他字段一律不允许。然后选择 Edit schema,在有需要的地方收紧它。这里把 period 改为可选,并限定为三个值:
1{2 "type": "object",3 "properties": {4 "period": {5 "type": "string",6 "enum": ["today", "this_week", "this_month"],7 "description": "The period to summarize"8 }9 },10 "additionalProperties": false11}有两样东西决定模型使用工具的效果:一是描述,模型只能靠它判断何时调用该工具;二是 schema。"additionalProperties": false 很重要,因为这样一来,带有 schema 未列出字段的调用在到达你之前就会被拒绝。
4. 发送测试调用
打开该工具的 ⋯ 菜单,选择 Send test call。ModelRiver 会调用你的端点一次,像真实请求一样签名,并标记为 "mode": "test",然后显示它发送的内容和收到的返回。
这在保存之前就可以使用,因此你可以一起调试端点和工具。组织所有者和管理员可以发送测试调用。
测试调用会发往工具的公网 HTTPS 地址。当你的端点只在你的机器上运行时,请启动 modelriver tools,并选择 My CLI,把测试调用发到它那里。
5. 保存并发布
保存工作流,然后发布它。与其他所有工作流设置一样,工具要在版本发布后才对生产流量生效。
6. 发送请求
在你的后端:
curl -X POST https://api.modelriver.com/v1/ai/async \ -H "Authorization: Bearer $MODELRIVER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "workflow": "sales_chat", "messages": [{"role": "user", "content": "How did we do this week?"}], "end_user": {"id": "user_812", "claims": {"store_id": "st_44"}} }'响应是常规的异步响应,包含 channel_id 和 ws_token。把它们传给前端,并用 Client SDK 连接:
1import { useModelRiver } from '@modelriver/client/react';2 3function Assistant() {4 const { connect, toolCalls, response, error, hasPendingRequest, cancel } = useModelRiver();5 6 // connect({ channelId, wsToken, websocketUrl, websocketChannel }) with what your backend returned7 8 return (9 <div>10 {toolCalls.map((call) => (11 <p key={call.id}>{call.label ?? call.name}{call.status === 'running' ? '' : ' ✓'}</p>12 ))}13 {hasPendingRequest && <button onClick={() => cancel()}>Stop</button>}14 {response?.status === 'success' && <pre>{JSON.stringify(response.data, null, 2)}</pre>}15 {error && <p>{error}</p>}16 </div>17 );18}请求运行期间,toolCalls 会显示“Reading this week's sales…”。最终响应带有回答和该请求的用量:meta.tool_loop 为 { "rounds": 2, "tool_calls": 1 },即套餐中的两次请求。
7. 查看请求
打开 Request Logs 并选择该请求。Timeline 会显示每个模型轮次,以及其下的每次工具调用及其耗时和 HTTP 状态。如果项目保存完整的请求和响应文本,每次调用还会显示其参数和结果。