> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# App subagents

> Register named agents your own server runs, with your app's tools and instructions

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](https://docs.salesive.com/apps/ai-tools.md). 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.

```bash theme={null}
curl -X PUT https://api.salesive.com/api/v1/app/subagents \
  -H "Authorization: Bearer app_<your-app-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subagents": [
      {
        "name": "restock_advisor",
        "description": "Suggests what to reorder and how much.",
        "instructions": "You advise a shop owner on restocking. Call get_stock before answering. Keep answers under 120 words.",
        "tools": ["get_stock"]
      }
    ]
  }'
```

* 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

| Field | Rules |
| - | - |
| `name` | Lowercase letters, digits, `_` and `-`, 1 to 30 characters, starting with a letter or digit. Unique per installation after `-` and `_` are treated as the same character, so `restock-advisor` and `restock_advisor` cannot both be registered. This is the name you run. |
| `description` | Required, up to 500 characters. Shown in your developer console, not to the model. |
| `instructions` | Required, up to 4000 characters. This is the system prompt for every run. |
| `tools` | Optional list of up to 16 tool names. Every name must already be registered for the same installation with `PUT /api/v1/app/tools`, or the request is refused with `unknown_tool`. |

Up to 16 subagents per installation.

## Run one

```bash theme={null}
curl -X POST https://api.salesive.com/api/v1/app/subagents/restock_advisor/run \
  -H "Authorization: Bearer app_<your-app-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "What should I reorder this week?",
    "context": "Slow week. Three SKUs sold out on Tuesday."
  }'
```

```json theme={null}
{
  "status": 200,
  "success": true,
  "message": "Subagent run completed",
  "data": {
    "output": "Reorder the cotton tee in medium first...",
    "toolCalls": [
      { "name": "get_stock", "ok": true }
    ]
  }
}
```

| Body field | Rules |
| - | - |
| `input` | Required, up to 4000 characters. The user turn. |
| `context` | Optional, up to 2000 characters. Facts your app already knows, passed as a second block so the model does not have to ask. |

### 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

| Status | `data.code` | Meaning |
| - | - | - |
| `404` | `subagent_not_found` | No subagent with that name on this installation. |
| `409` | `subagent_disabled` | The subagent exists but is turned off. |
| `502` | `subagent_failed` | The model call failed or the service refused it. |
| `502` | `subagent_unreachable` | Subagents are not configured on this server, or the agent service could not be reached. |
| `504` | `subagent_timeout` | The run passed 60 seconds. |

## Example: a route that runs one

```js theme={null}
app.post("/api/advice", async (req, res) => {
    const answer = await fetch(
        "https://api.salesive.com/api/v1/app/subagents/restock_advisor/run",
        {
            method: "POST",
            headers: {
                Authorization: `Bearer ${req.installation.appToken}`,
                "Content-Type": "application/json",
            },
            body: JSON.stringify({ input: req.body.question }),
        },
    ).then((r) => r.json());

    res.json({ answer: answer.data.output });
});
```

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](https://docs.salesive.com/apps/ai-tools.md) instead. If you already run an MCP server,
[MCP server tools](https://docs.salesive.com/apps/mcp-server-tools.md) may be a better fit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.