文档

抢先体验

你的第一个托管工具

一个端点,一个工具,一次请求。从空白的 Tools 选项卡到一个基于你自己数据的回答,大约十五分钟。

本指南为一个聊天工作流添加一个工具 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)

JAVASCRIPT
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 = crypto
21 .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 signed
35app.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)

PYTHON
1import hashlib, hmac, json, os, time
2from fastapi import FastAPI, Request
3from fastapi.responses import JSONResponse
4 
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 False
19 if abs(time.time() - int(timestamp)) > tolerance_seconds:
20 return False
21 
22 signed = f"v2.{timestamp}.{call_id}.".encode() + raw_body
23 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 True
27 return False
28 
29@app.post("/tools/sales-summary")
30async def sales_summary(request: Request):
31 raw_body = await request.body() # the exact bytes ModelRiver signed
32 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 并填写:

字段值
Nameget_sales_summary
Description for the modelReturns 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 labelReading this week's sales…
Endpoint URLhttps://api.yourapp.com/tools/sales-summary
Timeout10(秒)
What does calling it do?Only reads data

在 Example arguments 中,输入一次调用应携带的参数示例:

JSON
1{
2 "period": "this_week"
3}

选择 Build parameters from example。ModelRiver 会根据示例推导出 JSON Schema,并在 Parameters 下列出参数:每个键都会成为必填参数,其他字段一律不允许。然后选择 Edit schema,在有需要的地方收紧它。这里把 period 改为可选,并限定为三个值:

JSON
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": false
11}

有两样东西决定模型使用工具的效果:一是描述,模型只能靠它判断何时调用该工具;二是 schema。"additionalProperties": false 很重要,因为这样一来,带有 schema 未列出字段的调用在到达你之前就会被拒绝。

4. 发送测试调用

打开该工具的 ⋯ 菜单,选择 Send test call。ModelRiver 会调用你的端点一次,像真实请求一样签名,并标记为 "mode": "test",然后显示它发送的内容和收到的返回。

这在保存之前就可以使用,因此你可以一起调试端点和工具。组织所有者和管理员可以发送测试调用。

测试调用会发往工具的公网 HTTPS 地址。当你的端点只在你的机器上运行时,请启动 modelriver tools,并选择 My CLI,把测试调用发到它那里。

5. 保存并发布

保存工作流,然后发布它。与其他所有工作流设置一样,工具要在版本发布后才对生产流量生效。

6. 发送请求

在你的后端:

Bash
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 连接:

TSX
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 returned
7 
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 状态。如果项目保存完整的请求和响应文本,每次调用还会显示其参数和结果。

下一步