Agent: AI that calls your API
Some questions need a lookup you can't plan in advance. Give a workflow tools: endpoints of yours, each with a name and a schema. The model decides which to call, ModelRiver makes the signed calls inside limits you set, and your endpoint decides what each user may see. Your database never leaves your backend.
The four patterns
Sync
SimplestYour server sends a request and gets the full AI result back in the same call.
POST /v1/aiSee how it works →Async
Live to usersGet a channel back right away. The result streams to your users and arrives at your webhook.
POST /v1/ai/asyncSee how it works →Backend pipeline
Your data in the loopAI steps and your backend take turns. ModelRiver calls you when a step needs your data.
POST /v1/ai/async + backend stepsSee how it works →Agent
AI calls your APIThe model decides which of your tools to call. Each tool is an endpoint of yours, and ModelRiver makes the signed calls.
POST /v1/ai/async + toolsHow an agent runs
Example: a customer asks where their order is. The model calls your order tool, your endpoint checks who is asking, the model writes the answer.
- Your backend
Start the run
Your backend calls
{ messages, "end_user": { "id": "cus_812" } }POST /v1/ai/asyncon a workflow with tools, and says who is asking. You get a channel back right away. - ModelRiver
The model picks a tool
The model reads the question and asks for one of your tools. ModelRiver checks its arguments against the tool's schema.
get_order { "order_id": "1234" } - Your endpoint
Your endpoint is called
A signed POST brings the tool's name, the arguments and the end user your backend named. The model never sees who the end user is.
POST /tools/order { tool, arguments, end_user } - Your endpoint
Reply with your data
Check who is asking, look up the order, and return only the fields the model needs, as JSON, within the tool's timeout (10 seconds by default).
{ "status": "shipped", "eta": "Thursday" } - ModelRiver
The model answers
The model reads the result. It may call more tools, then writes the answer. 5 model rounds and 16 tool calls by default.
- Your users' browser
See it live
Your app shows which tool is running, then the whole answer arrives over the WebSocket channel.
tool_call_started → response
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 });
});When to use an agent
Use it when
- The model should decide what to look up, like an assistant that answers open questions
- Your app already has endpoints the AI can reuse: orders, accounts, reports
- One question may need several lookups, or none
Pick another pattern when
- One model call is enough: use Sync or Async
- The steps are always the same: a backend pipeline runs them in a fixed order
- The answer must stream token by token: for now, an agent delivers the whole answer
What ModelRiver handles
5 rounds
Per request
Model calls in one request, 2 to 10. Tool calls are capped too, at 16 by default.
Asks first
Tools that change something
A tool that cancels, sends or books runs only after the end user approves that call. It is sent once, never retried.
Signed
Every tool call
Each call is signed (HMAC-SHA256) and names the end user your backend sent, so your endpoint decides what that user may see.
Logged
Every round
Each model round and tool call shows up in your request logs, with its duration and status.