---
name: backprompter
description: Build apps on Backprompter — write agent JSON for upload, wire a frontend to the browser SDK, call agents from a server, and configure RAG, tools, combo agents and payments. Use when someone is building on the hosted Backprompter platform (backprompter.com), writing or editing an agent definition, embedding the chat, or integrating an app with the Backprompter API.
---

# Building on Backprompter

Backprompter hosts AI agents. A developer defines agents in the builder, then
calls them from their own frontend or backend. You can write an agent as JSON
for them to upload, and write the code that talks to it.

The builder, where developers sign in or create an account, is
https://app.backprompter.com. The website, pricing and developer docs are on
https://backprompter.com (for example https://backprompter.com/docs.html).

**Two things you cannot do from here:** you cannot see their app, and you cannot
guess ids. App Key, collection ids and document ids come from their builder —
ask rather than invent. Anything named `scope:...` or a bare document id in the
examples below is a placeholder.

## Writing an agent

The builder round-trips JSON: **⬇️ JSON** on an agent downloads it, and import
applies a JSON file as a new version. So the useful thing you can produce is a
complete agent definition they paste in.

```json
{
  "name": "policy-answers",
  "summary": "Answers employee questions from the staff handbook.",
  "instructions": "You answer questions about company policy...",
  "model": "anthropic/claude-sonnet-4-5",
  "temperature": 0.7,
  "maxTokens": 3000,
  "artifactType": "chat",
  "isRoutable": true,
  "userContext": true,
  "ragSources": ["scope:<collection-id>"],
  "deepSearch": false,
  "webSearch": false,
  "webFetch": false,
  "toolRefs": [],
  "mcpExposed": false,
  "isComboAgent": false,
  "subAgentIds": [],
  "shareFullContext": false
}
```

Every field, and what it does:

| field | values | notes |
|---|---|---|
| `name` | string | Identifies the agent. Unique within the app. |
| `summary` | string | How the router decides this agent fits a message. Write it as what the agent handles, not as praise. |
| `instructions` | string | The system prompt. `__TIME_STRING__` is replaced with the current time. |
| `model` | OpenRouter slug | Empty means `anthropic/claude-sonnet-4-5`. Must have a zero-data-retention provider on OpenRouter: every request asks for one, and a model without one fails with a message saying so. Browse the ones that do at https://openrouter.ai/models?zdr=true. |
| `temperature` | 0–1 | Defaults to 0.7. |
| `maxTokens` | number | Defaults to 3000. The builder's field caps at 4000. |
| `artifactType` | `chat`, `markdown`, `html`, `charts`, `javascript` | `chat` is an ordinary reply. The others produce a document the app renders and can edit in place. A `javascript` agent replies with JavaScript only, called directly or as a sub-agent: each reply is checked (compiled, never run on the server), a reply that isn't code gets one more try, and a second miss is an error. Math in chat and markdown replies is drawn with KaTeX when written as `$...$` or `\(...\)` inline, or `$$...$$` or `\[...\]` on its own. |
| `isRoutable` | bool | Whether the router may pick this agent. Default true. |
| `userContext` | bool | Whether the end user's profile is appended to the prompt. Default true. |
| `ragSources` | array | See *Retrieval* below. |
| `webSearch` | bool | Appends `:online` to the model, so the provider searches the web. |
| `deepSearch` | bool | Digs further in BRAG collections when a question needs it. Default false. See *Retrieval*. |
| `webFetch` | bool | Lets the model fetch URLs it finds in the message. |
| `toolRefs` | array | App-level tools, defined once on the app: an API tool's name, `mcp:<server>` for every tool an MCP server offers, or `mcp:<server>/<tool>` for one. See *Tools*. |
| `mcpExposed` | bool | Offers the agent as a tool to MCP clients that hold one of the app's API keys. Default false. See *Calling agents from MCP clients*. |
| `isComboAgent` | bool | See *Combo agents*. |
| `subAgentIds` | array of agent names | Only for a combo. |
| `shareFullContext` | bool | Whether sub-agents see the whole conversation. |

`ragSource` (singular) is still accepted for older definitions. Write
`ragSources`; the platform keeps the singular field in step.

## Retrieval

`ragSources` takes any number of entries, of three kinds:

- `"knowledgebase"` — everything indexed in the app
- `"scope:<collection-id>"` — one indexed collection
- `"<docId>"` — one whole document, injected in full rather than searched

Mixing is allowed: several collections and several documents together. Their
contexts are concatenated. A document kept in full is attached as a file rather
than as text.

Files can also be dragged onto the Files window to upload them.

**Updating a file:** in the Files window, select the file and click **Replace…**,
drag the new version onto that file in the list, or upload a file with the same
name and choose to replace it. The file keeps its
id, description and collection, so agents that use it, directly or through its
collection, need no change. An indexed file is re-indexed in the background and
the old version is searched until the new one is ready; if indexing fails, the
old version stays. Replacing costs the same as uploading the file new, and a
file attached whole can't grow past its size limit (index it first). Evaluations
from before a replacement were run against the old version.

**BRAG collections.** BRAG gives a collection a connected memory, so agents
answer from the full context around what they find, across sections and files.
A collection can be made a BRAG collection in the Files window: pick it in the
collection list and click **Index as BRAG**, or tick **as BRAG** when indexing
files into a new collection. It is built from what is already indexed, so
nothing is uploaded again and it costs nothing. A reply that draws on a BRAG
collection can use more input tokens. Nothing changes in the agent JSON:
`scope:<collection-id>` and `knowledgebase` work as before, and files added,
replaced or moved into the collection are included automatically. That includes
large files, which are indexed as they are uploaded: they go to the collection
picked in the list, or to a new one (BRAG if **as BRAG** is ticked). **Turn
BRAG off** returns it to ordinary search.

**Deep search** (`deepSearch: true`, or the Deep search tick on the agent)
makes that agent dig further in BRAG collections when a question needs it, and
leave out what does not belong. It adds a few model calls, charged like any
other call, and a second or two to a reply that searches. It only does anything
when the search reaches a BRAG collection. Use it for agents that answer from
long, structured documents where the first passages found are rarely the whole
answer; leave it off for quick FAQ-style agents.

**Memory map** (Files window) draws every indexed collection as a graph, BRAG
or not: the files first, then each file's sections, then the passages; click
or zoom to open. In BRAG collections, coloured lines are connections between
passages, found by BRAG or drawn by hand, hidden or shown with the **Links**
button. Click a link to see why it is there, tag it or remove it (a removed
link stays removed when the file is indexed again); a passage's panel has
**Link it to another passage…** to draw one. Files, sections, passages and
links can be tagged there, and the Find box searches names, passage text and
tags. In the builder's **Show sources**, whenever a reply retrieved passages,
the panel has two tabs: **Passages**, the list, and **Map**, those passages on
the memory map inside the panel; clicking a passage there shows it as the list
does, with the sentences the answer rests on marked, and **Full screen** opens
the whole map.

Two behaviours worth designing around:

**Retrieval is gated.** Before searching, a classifier decides whether the
message needs the documents at all and writes the search query. Greetings and
small talk retrieve nothing. You do not control this from the agent JSON.

**The nearest k are taken across everything selected**, so a large collection
crowds out a small one. If a small collection must always be represented, give it
its own agent rather than adding it alongside a large one.

## Combo agents

A combo agent coordinates other agents. Set `isComboAgent: true` and list
`subAgentIds`. In the builder, mentioning an agent as `@name` in the
instructions makes it a sub-agent.

Three modes, chosen by the **first line of `instructions`**:

- `parallel` — every sub-agent runs at once on the user's message
- `serial` — each runs in turn, seeing the previous one's output
- anything else — a coordinator model decides who to call and when, up to 7 rounds

For `parallel` and `serial`, list the sub-agents on the lines after the keyword
to fix their order.

**How the coordinator works.** Each sub-agent is a tool the coordinator calls
with an instruction. It can call several sub-agents in one step when their work
is independent; they run at the same time. Each result comes back labelled
`run_<n>`. The coordinator then writes the final answer, or passes one
sub-agent's result to the user unchanged (useful for charts and HTML). A
sub-agent receives its own instructions, the user's profile (unless its
`userContext` is false), the conversation, what has happened in the
coordination so far, the coordinator's instruction and the user's message, and
it uses its own model, tools, web access and documents.

The combo's own `toolRefs`, `webSearch`, `webFetch` and `ragSources` work too:
the coordinator can use them alongside its sub-agents.

**Limits.** Combos cannot nest (a combo used as a sub-agent answers as a plain
agent). One reply allows 7 coordinator rounds and 12 calls in total (sub-agents
and the combo's own tools). If the combo's model can't take tool calls (some
image, search and older models on OpenRouter), the coordinator uses an older
text format instead. In that case the combo's own tools, web access and
documents are not used, and the builder shows a note under the model field.

**Unfinished replies and Continue.** If the coordinator reaches the limit
before the task is done, it answers with what it has so far and what is left.
The result then has `unfinished: true` and a `checkpoint`: a short run id
(`bpr_` + 22 characters). The run is saved on Backprompter's servers for 7
days, works only for that app, and can be continued more than once (a failed
request can be retried). In the builder and the hosted chat a **Continue**
button appears under the answer. From the API, send `continue_from: <checkpoint>`
to `/public/run` (`user_prompt` may be empty), or pass `continueFrom` to
`run()` in either SDK; `autoContinue: n` makes the SDK continue up to n times
(max 20) by itself. It carries on with a fresh limit and counts as a new
message. These replies are not available on the older text format.

**Code sub-agents.** A sub-agent with `artifactType: 'javascript'` writes code.
The code runs in the browser over the user's data, never on the server: in the
builder, in the hosted chat (a **Data (CSV)** button appears when the app has a
code agent), and with the browser SDK (`run({ data: { name: csvText | rows } })`;
the result has `codeRuns`, or `output` / `codeError` for a code agent called
directly). The reply pauses with `pending_code`, the client runs it and sends
`continue_from` + `code_results`; the coordinator gets the output or the error
and carries on, for example asking for a fix. Code steps are not new messages;
at most 10 code runs per reply. Server SDK callers pass `clientRunsCode: true`
and run `pending_code` themselves; without it (and in Slack) the code comes back
to the coordinator as text. Either way the sub-agent is given the request as a coding task and always replies with JavaScript; a failed run shows the coordinator the code next to the error.

## Tools

Tools are defined on the app in the builder (**🧰 Tools**), not in agent JSON —
an agent only references them by `toolRefs`. There are two kinds:

- **API tools** — one HTTPS endpoint each (GET, or POST with a JSON body). The
  ref is the tool's name.
- **MCP servers** — a remote MCP server (Streamable HTTP, https), added by
  name and URL with an optional key. `mcp:<server>` gives the agent every tool
  the server offers *when it runs*, so tools the server adds later arrive within
  about 5 minutes; `mcp:<server>/<tool>` pins one tool.

Each tool or server has an **Auth** choice: **Bearer token** (just the key,
sent as `Authorization: Bearer <key>`; typing a key picks it), **Custom
header**, **Query parameter**, or **No auth**. The key is stored encrypted.

The model sees an MCP tool as `<server>__<tool>`. Ask the developer for the
server name they used rather than guessing it. Only public https hosts are
allowed, OAuth-only MCP servers can't be connected yet, and an agent gets up to
5 rounds of tool calls per reply. Use a tool-calling model; small models invent
arguments.

## Forwarder agents

A forwarder connects an agent the developer hosts elsewhere, behind an API tool
or an MCP server, so Backprompter's evaluations, mock users, Auto, Slack and the
SDK can talk to it without seeing its prompt. Set `"role": "forwarder"` and
give it `toolRefs`:

```json
{
  "name": "my-hosted-agent",
  "summary": "Answers order and delivery questions.",
  "role": "forwarder",
  "instructions": "",
  "model": "anthropic/claude-sonnet-4-5",
  "toolRefs": ["mcp:myagent/chat"]
}
```

- Each reply makes one model call and one tool call. The model fills in the
  tool's arguments from the conversation (and, with several tools, picks one);
  the tool's output is the reply, unchanged. The model never sees the output.
- `instructions` is only an optional note on filling in the call or choosing
  a tool, e.g. "Always set language to en."
- Backprompter fills in the conversation itself, so the model doesn't have to
  copy it: an argument named `messages` gets the whole chat as
  `{role, content}` turns, the new message included; `history`,
  `conversation`, `chat_history` or `conversation_history` get the earlier
  turns only. A list argument gets a list; a text argument (all API-tool
  parameters) gets it as JSON text. Name the tool's message argument
  `message` so the model knows where the user's words go.
- RAG, web search, web fetch, profile context, temperature, max tokens and
  artifact type don't apply. A forwarder is never a combo, but it can be a
  combo's sub-agent. Team policies can't shape its replies.
- Forwarded calls wait up to 60 seconds, and replies are cut at 100,000
  characters. An HTTP error comes back as the reply, with its status line.
- The role is chosen when the agent is created and never changes: an existing
  agent can't become a forwarder, and a forwarder can't become anything else.
  So `"role"` is read only when an uploaded JSON creates a new agent; importing
  it onto an existing agent as a version leaves the role as it was.
- Billing: the usual agent call plus one model call to fill in the tool call.
  The forwarded call itself is not charged as a lookup.

## Choosing a model

`model` is an OpenRouter slug. Two traps:

**Reasoning models bill their thinking against `maxTokens`.** A model that
reasons can spend the whole budget before writing anything, and you get an empty
reply. Measured: `google/gemini-3.8-flash` used 189 of 200 tokens reasoning and
was cut off mid-sentence; `z-ai/glm-5.3` returned nothing at all. If an agent
uses a reasoning model, give it room — the default 3000 is enough for ordinary
replies.

**Instruct and thinking variants differ by one word in the slug.** For example
`qwen/qwen3-235b-a22b-2507` is the instruct model; `...-thinking-2507` is not.

## Talking to an agent from a browser

Load the browser SDK from its CDN with a script tag. It is not on npm, so there
is nothing to install; it sets the global `Backprompter`.

```html
<script src="https://backprompter-sdk.pages.dev/backprompter-full.min.js"></script>
```

```js
Backprompter.setAppKey('<App Key from the Deploy dialog>');
await Backprompter.signInAnonymously();          // or signIn / signInWithGoogle
const { response } = await Backprompter.run({ userPrompt: 'Hello' });
```

The message goes in `userPrompt`; `run` throws without it. Add `agentId` to call
one agent directly instead of letting the router choose.

To show the answer as it is written, pass `stream: true` with
`onDelta(piece, textSoFar)` and optionally `onStatus(event)`. The call still
resolves with the complete result, which is the text to keep. `onStatus` gets
`meta` (which agent answers, and `streaming: false` when no text will stream),
`status` (`routing`, `retrieving`, or `tool` with its `name`) and `reset` (text
written before a tool call; clear it). Only chat answers stream: charts and
other artifact types, combo agents, `genDiff` edits and forwarders arrive whole.
The hosted chat streams by default; untick "Stream replies" in the Deploy dialog
to turn it off. "Show intermediate steps" under it adds notes such as
"Searching documents..." until the answer starts; for a combo agent, a note for each sub-agent it calls ("Using proof_digger..."). The builder's test chat has its own pair of switches
above the message box, to see answers the way streaming users will.

What the SDK exposes, by area:

- **auth** — `signIn`, `signUp`, `signOut`, `signInAnonymously`, `signInWithGoogle`, `signInWithSecret`, `signInWithCustomToken`, `signInWithExternalAuth`, `onAuthChange`, `currentUser`, `requestPasswordReset`
- **running agents** — `run`, `runWithFiles`, `runWithApiKey`
- **conversations** — `saveConversation`, `getConversation`, `listConversations`, `deleteConversation`, `uploadConversationFile`
- **artifacts** — `storeArtifacts`, `getArtifact`, `listArtifacts`, `deleteArtifact`
- **app data** — `getData`, `deleteData`, `search` (vector search over conversations and artifacts)
- **files** — `getPromptFileType`, `extractPromptFileText`, `readPromptFileAsDataUrl`, `buildPromptWithFiles`, `indexAttachment`, `deleteAttachmentIndex`
- **voice** — `connectVoice`, `createVoiceAgent`
- **payments** — `getEntitlements`, `createCheckoutSession`, `createBillingPortalSession`

Payments are **browser-only**, and deliberately: `createCheckoutSession` and
`createBillingPortalSession` return a URL to redirect to, and every payment call
acts on the signed-in end user. Money goes to the developer's own connected
Stripe account.

Give every paying user a way to manage their subscription. The billing portal
is Stripe's own page for cancelling, resuming and changing cards; Backprompter
sets it up on the developer's Stripe account, so there is nothing to configure.

```js
const { active, entitlement } = await Backprompter.getEntitlements();
if (!active) {
  const { url } = await Backprompter.createCheckoutSession({ successUrl, cancelUrl });
  location.href = url;
} else if (entitlement?.mode === 'subscription') {
  // e.g. behind a "Manage subscription" button
  const { url } = await Backprompter.createBillingPortalSession({ returnUrl: location.href });
  location.href = url;
}
```

- Cancelling takes effect at the end of the paid period, and access lasts until then.
- `createCheckoutSession` refuses while the user still has access, so nobody pays twice. It also refuses while a renewal is failing (`code: 'payment_past_due'`); send that user to the billing portal to update their card.
- The hosted chat already shows subscribers a Manage subscription button.
- A user who cancels and later subscribes again keeps their saved card.
- `createBillingPortalSession` fails until the user has paid at least once.

## Saving conversations

`saveConversation(conversationId, messages, metadata)` keeps a transcript per
end user; `getConversation`, `listConversations` and `deleteConversation` read
and remove it. The same four exist on the server SDK's `forUser(...)`.

- Save as often as you like, with the whole history or only the new messages:
  the server appends what is new and leaves the rest untouched. Every stored
  message gets an `id`, returned by the save; include ids on the messages you
  send and they are matched by id, otherwise by content. `mode: 'append'` or
  `mode: 'replace'` (fourth argument, `{ mode }`) says so outright.
- A history the server compacted starts with a `Conversation summary (earlier
  turns):` system message. Save it as it is: the summary is stored beside the
  transcript (`summary` on the result and on `getConversation`), and the stored
  messages stay whole.
- A conversation can hold 5,000,000 characters; one message, 400,000. Long
  conversations are stored in pages behind the scenes; `getConversation`
  returns the whole transcript.
- Uploaded files: with **Keep uploaded files** ticked in the Deploy dialog,
  `uploadConversationFile(conversationId, file)` stores the file and returns
  `{ uploadId, name, contentType, bytes }` to put on a message's `attachments`
  in the next save; `getConversation` returns each with a short-lived `url`.
  Storage is billed to the app owner as file storage. With the setting off (the
  default), only attachment names are kept.
- `search` finds conversations by meaning; the embedding covers the first
  8,000 characters and is recomputed only when they change.

## Keeping your own login

An app that already has its own users does not have to move them to
Backprompter. The developer's backend exchanges one of its own user ids for a
session the browser can use.

Server side, holding the API key:

```js
const r = await fetch(`${BACKEND}/api/app/${appId}/enduser/exchange`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-bp-api-key': process.env.BP_API_KEY },
  body: JSON.stringify({ externalId: myUser.id })   // optionally `claims`
});
const { customToken, uid, tenantId } = await r.json();
```

Browser side, handing the SDK a function that fetches one:

```js
await Backprompter.signInWithExternalAuth(() =>
  fetch('/my-backend/backprompter-token').then((r) => r.json())
);
```

It accepts the token as a string or as `{ customToken }`, and signs in with it.

Three things that matter:

- **Server-to-server only.** It takes the API key and never an end-user token.
  Whoever can call it can act as any user of the app, so it must not be reachable
  from a browser.
- **The key needs the `identity:exchange` scope.** Without it the call is
  refused; a key made only for `/public/run` will not work.
- **The uid is derived** from the tenant and the external id. The same person
  always returns to the same data, and the caller cannot choose it.

To keep every call server-side instead, the server SDK's `forUser(externalId)`
acts for one of your users without a browser session at all.

## Talking to an agent from a server

The server SDK has one method.

```js
import BackprompterServer from 'backprompter-server';
const bp = new BackprompterServer({ apiKey: process.env.BP_API_KEY, tenantId: '<App Key>' });
const { response } = await bp.run({ userPrompt: 'Hello', agentId: 'policy-answers' });
```

It takes the same `stream: true` / `onDelta` / `onStatus` options as the
browser SDK. It calls `POST /public/run` with an `x-bp-api-key` header. Keys are created in
the builder, bound to one app, and capped at 10 active per app; the admin can
revoke them in the Deploy dialog. The server SDK has no payments and no
end-user auth — there is no signed-in user in that context.

API keys need a paid plan (Solo Dev, Teams or Enterprise). A call is refused with
HTTP 402 when the app's admin can't pay for it, for example when their balance
has run out; handle that rather than retrying.

Plans: the **Free Trial** gets up to 2 agents and a lifetime allowance of 50
messages or $1 of model usage, whichever comes first, and must verify its email
first (HTTP 403, `code: "email_not_verified"`). It cannot deploy in any form
(chat, API keys, MCP, Slack), invite teammates or set policies; those answer
HTTP 402 with `code: "upgrade_required"`. **Solo Dev** ($5 a month, from
the balance) lifts the limits and deploys; it includes one person (the owner), and
each person invited past that is $29 a month, charged at the invite and with
each monthly fee. **Teams** ($129) includes 25 people and 25,000 agent calls a
month (the agent call fee is waived; lookups and model cost are not), and is
the first plan with BRAG (BRAG collections and deep search; elsewhere they are
refused with 402 `upgrade_required`, and an existing BRAG collection is
searched like any other). **Enterprise** (set up by Backprompter; price on
request) adds auditors, admin switches, 1,000 people and 250,000 agent
calls included, and no batch limit; invites past its people are refused (409
`member_limit`). People are counted once each across all the owner's apps,
pending invites included. Batch evaluations a day: 5 on the Free Trial and
Solo Dev, 20 on Teams (402 `batch_eval_limit` past it). Owners move between
Solo Dev and Teams in the account window: up starts a new month at once,
charged in full; down happens when the paid month ends; nobody goes back to
the Free Trial, and money added to the balance is not refundable. Moving up
needs a balance of twice the new plan's monthly bill first ($10 Solo Dev, $258 Teams, plus twice any
extra people; HTTP 402 `code: "needs_credits"` with `need`, `have` and
`short` otherwise), and adding to the balance, by hand or automatically, must
leave at least twice the monthly bill and is never under $5. Accounts that were on
Developer are Solo Dev, Dev Pro is Enterprise, and the old Hobby plan is the
Free Trial. An account Backprompter priced on its own (usually Enterprise)
sees that price in its account window, and money Backprompter adds by hand
(for testing or early adopters) are listed there with their note.
On the paid plans, use is charged from the balance (prepaid, in dollars; the
builder calls it Balance) in two prices. An **agent call**
($0.015) is each agent reply: one per message, plus one for each sub-agent a
combo agent calls. A **lookup** ($0.01) is added for each call to one of the
app's own tools (API or MCP), each model request made with web search on, each
reply grounded in the app's files (RAG or BRAG: one per reply, however many
passages), and each file attached to the message, on every message it is sent
with (images taken out of a document count with the document). Model cost
(including routing, summaries and other steps behind a reply) is passed through
at what OpenRouter charges, with no markup; with the app's own OpenRouter key
the tokens go on that key. Storage is $0.05 per MB per month, and deploying an
app is a one-time $10. An embedding from `/public/embed` is one lookup. The Free
Trial pays no per-use fees.
Prices and these numbers can change, so take current figures from the Billing
window or the pricing page.

Where to see what was used: the account window (the balance badge) has tabs
for Plan, Balance, People and Usage; Usage shows charges for the last 30 or
90 days, 12 months or all time (kept for good), and a model
table (calls, tokens and cost per model, own-key calls apart). The Usage
button in the builder's Users section opens, for the deployed app (hosted
chat, SDK, API key, MCP, not builder test chats), each agent and each end user
with messages and what they cost the app owner, this month and all time. API key calls show as one
row, since they have no signed-in user.

**Auto top-up** (paid plans: Solo Dev, Teams and Enterprise): in the account
window, under Balance, the developer saves a card on a Stripe page that charges
nothing, then chooses when to top up ("when the balance falls below $5"), how
much to add each time (at least $5), and the most to add in one month. The
point plus the amount must keep the plan's minimum balance ($10 Solo Dev, $258
Teams), and the monthly limit must allow one top-up; saving less is refused
(HTTP 400 `code: "auto_top_up_too_low"` with suggested numbers), and moving
up a plan with auto top-up too low is refused the same way (409) while the
account window offers to raise it, or cancels the move. Whenever the
balance drops below that amount, Backprompter charges the saved card and adds
to the balance, so deployed apps don't stop at $0. A declined card, or a bank
that wants the cardholder to approve the payment, turns auto top-up off and
the Billing window says why; reaching the monthly limit only pauses it until
next month. It can be turned off, or the card changed or removed, at any time.

## Calling agents from MCP clients

Backprompter is also an MCP server, at `<backend>/mcp` (the Deploy dialog shows
the exact URL and ready-made client setup). Each agent with `mcpExposed: true`
is one tool, named `<app display name>_<agent name>` (cleaned to
`[A-Za-z0-9_-]`, app part up to 16 characters, 40 in all). Its description is
the agent's `summary`, so write the summary as when to call it and what it
knows that the client's model doesn't.

- **Auth:** an app API key as `Authorization: Bearer <key>`, or `x-bp-api-key`.
  OAuth isn't supported, so for Claude Desktop connect through `mcp-remote` with
  the header.
- **Arguments:** `message`, plus an optional `conversation` (earlier
  `{role, content}` turns). Calls are otherwise independent.
- **Not offered:** `javascript` (code-execution) agents.
- **Limits:** about 30 calls a minute per key. Backprompter agents calling
  other Backprompter agents over MCP may nest only one level.

**One Backprompter agent calling another as a tool.** Exposed agents never
appear in a tools picker by themselves, and there is no built-in
`mcp:backprompter/...` ref. The calling app adds Backprompter's MCP server like
any other:

1. In the app with the agent: tick **Expose via MCP** on it and save, create an
   API key (**🚀 Deploy** → *API access*), and copy the MCP endpoint shown under
   *MCP server* in that dialog.
2. In the calling app: **🧰 Tools** → **+ Add MCP server**, with a name (e.g.
   `support_app`), that endpoint, Auth **Bearer token** and the key, then
   **Save tools**. The card lists one tool per exposed agent.
3. In the calling agent's Tools dropdown, tick the server or that one tool
   (`mcp:support_app` or `mcp:support_app/<tool>`), and save.

Within one app, use a combo agent instead; it needs no key. Each call is billed
to both apps' admins: the caller's run and the called agent's run.

## Team policies

An app's admin can set guardrails for every agent and rules for evaluations.
Backprompter puts them at the start of each agent's system prompt at run time,
marked as overriding the agent's own instructions. Editors can't see them. You
won't see them either, so if an agent ignores part of its instructions, a policy
may be the reason. Don't write instructions that try to override admin rules.

On Enterprise the admin can let editors and auditors read the policies (read
only), from the Team window.

## Teammates and roles

An app has one admin; people invited (👥 Team) are **editors**, or on
Enterprise also **auditors**. Everyone they run bills the admin.

- Editors build like the admin (agents, files, tools, evaluations, secret codes,
  Slack). They cannot deploy or unpublish the chat, pay the production fee,
  create or revoke API keys, or set up Stripe payments, unless the admin is on
  Enterprise and turned on **Editors can deploy** in the Team window (that
  covers deploying and unpublishing the chat; whether it also covers keys, the
  fee or Stripe is a Backprompter setting).
- Auditors chat with the agents, evaluate them (single and batch, saved
  versions included), view results, and keep their own mock users and
  evaluator agents. They cannot change other agents, files, tools or settings,
  deploy, or use "Suggest system prompt updates". Their refusals come back as
  HTTP 403 with `code: "auditor_read_only"`.
- Unless the admin turns on **Auditors can view agents, files and tools** in
  the Team window, auditors see the other agents by name, summary, role and
  model only: not their instructions or settings, not what saved versions
  contain, and not the files, API tools or MCP servers (HTTP 403,
  `code: "not_shared"`). They can still pick a saved version in Versions to
  chat with and evaluate; Backprompter gives the evaluator the hidden
  instructions itself and tells it not to repeat them. If an auditor asks you
  for a prompt they can't see, you don't have it either; help them evaluate
  instead.
- Only the admin invites, removes, changes roles, sets policies and deletes the
  app. How many people one app can have depends on the admin's plan.

In the builder, locked buttons stay visible but dimmed, and clicking one says
who can do it. If someone needs a locked action, the answer is to ask the admin
(or, on the Free Trial, to upgrade).

## Evaluating agents in the builder

The builder's Evaluations section rates each agent, and Auto (the meta-router),
by version: Now (what the test chat uses), Deployed and Best, each the average
of that version's own evaluations. A Scores picker chooses the source: the
developer's own 0-10 ratings, the built-in evaluator, or a custom evaluator
agent; sources are never mixed.

- **Evaluate this chat** scores the current test chat by hand. The built-in
  evaluator answers with a `Score: X/10` line and up to three short reasons.
- **Batch evaluate** runs many mock-user chats on the server and scores each
  one: pick the agent (or Auto), the evaluator, mock users, the number of runs,
  a range of turns per run (each run picks within it, 1 to 10; the form starts
  at 2 to 6), and optional topics, one per line (Suggest topics adds three
  written for the app and agent). Runs pair every mock user with
  every topic. At most 200 turns per batch, one batch at a time per app. Each
  turn uses two messages and each run one more for the evaluator, all on the
  app admin's plan. It tests the version the test chat used when it started.
  The admin's account can start 5 batches a day on the Free Trial and Solo
  Dev and 20 on Teams (all apps and teammates together; HTTP 402,
  `code: "batch_eval_limit"` past that, until midnight UTC). Enterprise has
  no limit.
- **Compare** in the batch form tests up to four variants of one agent: each is a
  version (current, deployed, or a saved version) plus an optional model that
  applies to this batch only and is never saved. Every variant gets the same
  runs (mock user, topic, turns) and the same evaluator; the 200-turn limit
  counts all of them. For a combo agent the model applies to the combo itself.
  Auto takes no variants. Results show each variant's average (best marked) and
  a side-by-side table of scores per mock user and topic.
- A batch keeps running if the builder is closed; its progress shows under the
  ratings while it runs, with Cancel (chats under way finish, the rest are
  skipped). Running out of balance stops it. If the servers restart meanwhile,
  the batch pauses and continues the next time the builder is opened. Results,
  including past batches, list each run's mock user, topic, turns, score and
  speed; a run opens its conversation and verdict, with each reply's times and
  tokens, and the developer can add a 0-10 rating there.
- Batches measure reply speed; "Evaluate this chat" doesn't. Replies run
  streamed, as in the chat. **Time to first text** runs from sending the message
  to the first piece of the reply and doesn't depend on the reply's length.
  **Reply time** runs to the complete reply. Both include routing, document
  search and tool calls, and the batch shows each one's average and the time 95%
  of replies came in under. **Throughput** is how fast the answer was written:
  output tokens per second from its first text to its end, leaving out routing
  and tool calls. Time to first text and throughput are blank for replies that
  arrive in one piece (combo agents, forwarders, output other than chat). Mock
  user and evaluator messages aren't counted. **Cost per reply** is what the
  agent's model calls cost for each reply (routing, tool steps and document
  search included), as OpenRouter reports it, without agent call or lookup fees. A batch
  comparing variants shows each variant's speed and cost. To find what is slow: a long time to first text with
  normal throughput points to routing, retrieval, tool calls or a model slow to
  start; low throughput points to the model.
- Batch runs have only the evaluator's score, so they show in the ratings when
  the Scores picker is set to that evaluator. "View all evaluations" lists every
  saved evaluation, filterable by agent, version, evaluator and source, and
  grouped by version with one average per evaluator and the group's speed; a row
  opens its conversation. Its columns for first text, average reply, tokens
  per second and cost per reply can be sorted. **Compare versions** above the
  list plots each version on two measures the developer picks (quality, their
  rating, cost per reply, time to first text, reply time, tokens per second;
  quality against cost at first). Quality there is one evaluator's average: the
  evaluator filter's, or the one that scored the most. Each version has its own
  colour; with grouping off, single evaluations show as faint dots too. Grouped
  versions can be ordered by any of those measures. Evaluating an agent with
  unsaved edits asks for a name for that version, offered again for the same
  settings. **Download report** opens a report of the evaluations
  shown (filters applied): each version's averages, then every evaluation with
  its full verdict and the developer's note, ready to save as a PDF from the
  print dialog.
- Evaluators see, for each reply, the tools it called with a short copy of
  each call's input and result, the web pages it cited and documents it
  retrieved, and on Auto which agent answered, so an evaluator agent can
  score tool use or routing. Every evaluator, built-in or custom, also gets a
  retrieval check: each reply's claims with the sentences from its documents and
  tool results that might bear on them. The evaluator decides whether each claim
  is supported, so its instructions needn't mention retrieval. Each reply with sources is one small extra model call at cost.
- An evaluator agent should put its score on its own line, such as
  `Score: 8/10` (any scale, written as X/Y or "X out of Y"), so it can be read
  and averaged. Short verdicts make batches faster.
- Evaluators are agents with the Evaluator role: created with + in the
  Evaluators box of the Evaluations section (starter prompt included) or by
  setting Role in the agent editor (not versioned, takes effect at once). Only
  evaluators and the built-in one are offered as evaluators; agent lists show
  them under an "Evaluators" heading and they can still be tested. Auto never
  routes to an evaluator. An uploaded agent JSON may carry `"role": "evaluator"`.
  A forwarder can't be made an evaluator, and an evaluator can't become a
  forwarder.
- An evaluator judging a forwarder is told that its replies come from an agent
  hosted elsewhere and that its internals aren't visible.
- Prompt suggestions are not offered for Auto, combo or forwarder agents.

## Embedding the chat

One line, from the Deploy dialog:

```html
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://backprompter-sdk.pages.dev/backprompter-widget.min.js"
        data-app-id="<App Key>"></script>
```

The viewport tag matters on phones: without it the page lays out at ~980px and
the browser zooms out, so the chat text comes out tiny.

## Attachments

An attached file travels with each message it is attached to, not in the
conversation history, so the model sees it whole for as long as it stays
attached; removing it from the attachment list stops sending it. When a long
history is compacted, attached-file text that an app kept in the history is
kept word for word rather than summarized, and the reply's
`additional_response.compaction` says how many recent messages were kept and
what was put in front of them; mirror that if you keep your own copy of the
history (the SDK's `runWithFiles` callers see the same field).

A text file over 100,000 characters is not sent whole. The builder, the hosted
chat and `runWithFiles` index it instead (one call, billed to the app owner like
retrieval): it is cut into passages, embedded, and each message gets the
passages that fit it best, so a question about any part of the file can be
answered. The platform sets the longest file it will index (1,000,000
characters unless the operator changed it); a longer one is refused with
`code: 'attachment_too_large'` and sampled instead. The index expires after 7
days. Spreadsheets and CSV files are cut by rows: every passage starts with the
header line, and no row is split. In your own code:
`indexAttachment({ name, text, kind })` returns an `indexId` to pass as
`attachmentIndexes` with `run`, or put it on a `promptFiles` entry as
`indexId`; `kind: 'table'` asks for row-wise cutting (the text is blocks
separated by blank lines, each starting with its header line), `'text'` for
paragraphs, and unset goes by the file name. `deleteAttachmentIndex(indexId)`
removes it early. The server SDK has `indexAttachment` and
`deleteAttachmentIndex` too, and `run` takes `attachmentIndexes`. If indexing
fails, the file is sampled (its start, middle and end) as before. In the
builder, files can also be dropped on the message box; a chip reads
"(indexing…)" until the server is done, and the file is not sent before that.

If the agent's model takes no images and images are attached (or were taken out
of a deck or Word file), the request is sent again without them and the reply is
based on the text; `additional_response.warnings` then holds
`[{ code: 'images_dropped', message }]`, which the builder shows as a note above
the reply. Show it in your own chat too, or pick a model with image input.

A PDF whose meaning is in screenshots or scans is not represented by its text.
The platform detects images and handles the file accordingly — small
image-bearing PDFs are sent whole to the model, larger ones have their images
extracted, described and indexed. Nothing in the agent JSON controls this.

When retrieval attaches a file, the system prompt names it as attached by the
app. Do not write instructions telling the agent to discuss "the file the user
sent" — it may not have come from them.

## Using Claude Code or another assistant to build on Backprompter

This document is the Backprompter skill, published at
github.com/planosophy/backprompter-skill (MIT). A developer who wants Claude
Code to write agents, wire the SDKs or call the API for them installs it with:

```
/plugin marketplace add planosophy/backprompter-skill
/plugin install backprompter@planosophy
```

Claude Code then uses it whenever they work on a Backprompter app;
`/plugin marketplace update planosophy` picks up new versions. Without the
plugin, the file can be saved as `.claude/skills/backprompter/SKILL.md` in one
project, or under `~/.claude/skills/backprompter/` for every project (the raw
file is at
raw.githubusercontent.com/planosophy/backprompter-skill/main/plugins/backprompter/skills/backprompter/SKILL.md).
It is plain Markdown, so Cursor, a Claude Project or any assistant that takes
project knowledge can use it as a reference too. The builder's own copilot
answers from this same file, plus a summary of the screen.
