Skip to main content
A subagent is a named agent your app defines once and runs whenever it needs an answer. You give it a name, a description, instructions and a subset of the tools you already registered for the app. Your server calls POST /api/v1/app/subagents/:name/run and gets text back. Salesive makes the model call and runs the tool loop. Your app does not need a model provider, a key, or a server that stays open while the agent works.

Who sees subagents

Nobody but you.
  • Merchants never see subagents. There is no switch on the installed app page and no scope to grant.
  • Ola does not call subagents. They exist for your app’s own code.
  • The developer console lists them under the app’s Subagents tab, so you can see what each installation registered and how many stores have it.
Subagents are separate from server-side AI tools. Tools are what Ola can call. A subagent is what your app can call.

Register your subagents

Send the whole list with PUT /api/v1/app/subagents and your app token. The installation, and therefore the store, comes from the token.
  • The request replaces the whole list for the installation. Send every subagent every time; one you leave out is removed.
  • Nothing is written until every subagent passes validation. A rejected request leaves the previous list in place and answers 400 with a data.code such as too_many_subagents, duplicate_name, instructions_too_long or unknown_tool.
  • GET /api/v1/app/subagents returns the list for the installation.

Subagent fields

Up to 16 subagents per installation.

Run one

What a run does

  1. The subagent’s instructions become the system prompt.
  2. input, plus context when you sent it, becomes the user turn.
  3. The model may call any tool in tools. Each call goes to your app the same way Ola’s tool calls do: a signed POST to the tool’s toolUrl, with X-Salesive-Signature and X-Salesive-Request-Id. There is no approval card, because your own code started the run.
  4. The final text comes back as output.

Limits

  • At most 6 tool calls per run.
  • At most 60 seconds per run. A run that passes the limit answers 504.
  • Any one tool result is cut at 4000 characters before it goes back to the model. The cut is marked in the text.
  • A tool that fails does not end the run. The model sees an error sentence, toolCalls records ok: false, and it carries on.

Errors

Example: a route that runs one

The app token is the one you received for the installation. It decides the store, so keep one token per installation rather than reusing one across shops.

When to use subagents

  • Your app needs an answer from a model, and you do not want to run one.
  • The answer depends on the store’s data, which your own tools already read.
  • You want the same instructions and the same tool set every time, without shipping a prompt from the browser.
If the work is something Ola should offer the merchant, register a server-side tool instead. If you already run an MCP server, MCP server tools may be a better fit.