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.

How 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.

  1. Your backend

    Start the run

    Your backend calls POST /v1/ai/async on a workflow with tools, and says who is asking. You get a channel back right away.

    { messages, "end_user": { "id": "cus_812" } }
  2. 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" }
  3. 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 }
  4. 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" }
  5. 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.

  6. 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
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 });
});

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.

Give your first workflow a tool