Documentation

Early access

Pipeline or tools?

Both connect a workflow to your backend. A pipeline follows steps you fixed. Tools let the model choose.

ModelRiver has two ways to bring your backend into an AI request. They solve different problems, and most products end up using both, on different workflows.

The difference in one line

  • A backend pipeline runs steps you put in order. The AI generates, your backend does its part, the result is delivered. Every request takes the same path.
  • Hosted tools let the model decide. You offer a set of endpoints; the model picks none, one or several, in whatever order the question needs.

Side by side

Backend pipelineHosted tools
Who decides what runsYou, when you build the workflowThe model, on each request
Path through your backendThe same every timeDepends on the question
How your backend is calledA webhook, answered with a callbackA signed POST, answered in the response
Can your backend change dataYesYes, after the end user approves each call (Approvals)
How long your backend may takeUp to 10 minutes per stepUp to 30 seconds per call
Requests on your planOne per AI stepOne per model round
Structured outputYesNot yet
Best atA process: generate, check, save, deliverA question: look up what's needed, then answer

Choose a pipeline when

  • The steps are known in advance. "Draft a reply, check it against policy in our backend, save it, send it."
  • Your backend must do something: write to the database, charge a card, open a ticket.
  • A step is slow, or waits on a person.
  • You need the same result shape every time, with a structured output.

Examples: scoring every inbound lead and writing the score to your CRM; turning an uploaded report into a summary that is saved before the user sees it; screening job applications against the same criteria.

Choose hosted tools when

  • You can't know in advance what the user will ask for. "How did we do this week?" needs sales; "why is the Berlin store behind?" needs sales, stock and staffing.
  • The answer depends on data only your backend has. Reading it is enough, or a change the end user can approve call by call (cancel this order, send this email).
  • You'd otherwise write the tool-calling loop yourself.

Examples: an assistant on an analytics page; a help panel that reads the signed-in user's plan and usage; an internal assistant that answers questions about a project's open tasks.

Do you need either?

Often not. If the data the model needs is known when the request is made, put it in the request. A workflow that gets the order's details in the prompt is faster, cheaper and easier to test than one that has to ask for them. Reach for tools when the model has to choose, and for a pipeline when your backend has to act.

Using both

One workflow can't have a pipeline and hosted tools together yet. Use two workflows: a tools workflow that answers questions (and makes changes the end user approves), and a pipeline workflow for changes that run without asking anyone. Your app decides which to call, usually from what the user selected rather than from what they typed.

Next steps