Backprompter Documentation

Everything you need to build, test, and ship AI agents — from your first system prompt to a production chat UI for your users.

What is Backprompter?

Backprompter is an AI agent development and deployment platform. It gives developers a workspace to create and refine AI agents (via system prompts), chat with them interactively, run structured evaluations, and then deploy a polished chat interface for end users — all without writing any backend code.

Ways to Use Backprompter

• Deploy a chat interface for end users with no backend or frontend code — details · tutorial
• Use Backprompter SDK on your frontend code with Backprompter's authentication — details · tutorial
• Use Backprompter SDK on your minimal backend code with your Backprompter API key — details · tutorial

Core Concepts

Getting Started

After signing in, the main Backprompter UI is divided into a left sidebar for configuration and a right chat pane for testing.

Backprompter Copilot

The Backprompter Copilot is a helper panel on the right of the builder. Open or close it with ✨ Copilot in the header; it opens by itself when you sign in, unless you closed it last time. Ask it how to do something, or for suggestions on the app and agent you have open. Its opening suggestions follow where you are — "How do I get started?" before you have an app, help with a first agent in a new app, and a review of your test chat once you have one.

With each question it sees a summary of your screen: your apps, the selected app's agents and their settings, the window you have open and what is in it, your recent test chat, and recent error messages. API keys and other secrets are never included. When it isn't sure of an answer — another product, an MCP server, current model names or prices — it can search the web, and lists the pages it used under its reply.

Its replies can include buttons: open a window, point at a button or field, switch app or agent, or put suggested text (such as a revised system prompt) into a field of the window you have open. Nothing happens until you click, and it never saves, deletes, deploys, or starts paid work such as an evaluation — you still click Save yourself.

Copilot questions are charged to the owner of the app you have selected, like any other work on the app — see Billing & Credits. The conversation is kept only in that browser tab; New starts over.

1. Create an App

1. Click the + button next to Apps in the sidebar.
2. Give the app a name and optional description.
3. You don't need to have an OpenRouter or OpenAI API key. But if you want to use your own keys you can optionally enable Bring Your Own Keys (BYOK) to supply your own OpenRouter and/or OpenAI API key.
4. Click Save. The app now appears in the Apps dropdown.

2. Create an Agent

1. Select your app in the Apps dropdown.
2. Click + next to Agents.
3. Fill in the Name and Summary fields.
4. Write the System Prompt — this defines the agent's behavior and personality.
5. Configure the model, temperature, max tokens, artifact type, and RAG source (see below).
6. Click Test Now to immediately start chatting, or Save and Commit to save as a committed version which you can reload anytime.

Agent Configuration Options

When creating or editing an agent, you can configure:

• Model — pick from the presets (e.g. openai/gpt-5.3-chat, anthropic/claude-3-haiku) or select Other OpenRouter… and paste any model ID from openrouter.ai/models.
• Temperature — controls randomness (0 = deterministic, 1 = creative).
• Max Tokens — caps the length of each response.
• Artifact Type — controls how responses are displayed in Backprompter's UI:
  • Chat — standard response that appears in the main chat area.
  • Markdown Artifact — rendered markdown in a side pane.
  • HTML Artifact — rendered HTML in a side pane.
  • Charts — rendered charts in a side pane.
  • Code Execution (JS over CSV data) — the agent writes JavaScript that runs in a secure in-browser sandbox over CSV data you attach; the computed result is shown. See Data-Analysis Agents.
• RAG — set to Knowledge Base to augment the agent's context with documents you've uploaded to the app (see Files & RAG).
• Tools — let the agent call external HTTP APIs and tools from MCP servers mid-conversation. Define them once at the app level, then tick the ones each agent may use (see Tools).
• Routable through meta-router — makes this agent a candidate when the meta-router automatically selects an agent from your app (see Meta-Router).
• Expose via MCP — offers this agent as a tool to MCP clients such as Claude Code or Cursor that connect with one of your app's API keys (see Use Agents from MCP Clients). Off by default.
• Include user profile context — prepends the current mock user's profile to the agent's context during testing.

Combo-Agents

A combo-agent is a special agent that orchestrates multiple sub-agents. Once you have built some agents, you can build a combo-agent simply by tagging other agents in the system prompt. You can describe in natural language how and when to call the sub-agents, and the combo-agent will handle the routing and context management automatically.

Example system prompt that creates a combo-agent:

        1. Call @ResearchAgent with the user's question.
        2. If @ResearchAgent is unable to answer, tell the user that the question is out of scope.
        3. If @ResearchAgent is able to answer, pass the result to @SummaryAgent and ask it to produce a one-paragraph summary.
        4. Forward the summary to the user.

Meta-Router

The meta-router automatically picks the best agent to handle a user message. It is useful when a single app contains several specialized agents and you want the system to route automatically.

1. To include an agent in the meta-router, ensure Routable through meta-router is checked.
2. Click the 🔀 button in the Agents section header to open the routing settings.
3. Set a Default agent — used as a fallback when routing confidence is low.
4. Optionally enable Prefetch default agent to run the default agent in parallel with routing, reducing latency.
5. Click Save.

To test the behavior of meta-router, select Auto in the agent dropdown on the chat interface.

You don't need to write anything about routing into your agents' instructions. When the meta-router sends a message to a chat agent in an app that also has artifact agents (markdown, HTML, charts or data analysis), Backprompter adds a short note telling it that requests for those belong to the other agents. Agents you pick directly never get this note.

Tools: API Tools and MCP Servers

Tools let an agent fetch live data or take actions during a conversation. You describe when a tool should be used; the model decides to call it, Backprompter runs the call on the server with your stored credentials, feeds the result back, and the agent answers. There are two kinds, both defined once per app:

• API tools — a single HTTPS endpoint you describe yourself.
• MCP servers — a remote Model Context Protocol server; every tool it offers becomes available to your agents.

Open the app's tools with the 🧰 Tools button in the app bar, or with Manage app tools… under Tools in the agent editor.

Add an API tool

1. Click + Add API tool and fill in:
   • Name — the function name the model sees (letters, numbers, underscore), e.g. get_weather.
   • Description — when the agent should call it.
   • Method and URL — GET or POST, and the https endpoint. Use {param} for path values, e.g. https://api.example.com/weather/{city}.
   • Parameters — the inputs the model fills; mark each as query, path or body (body parameters are sent as JSON, POST only).
   • Auth — optional header or query key. The secret is stored encrypted and never sent to the model or browser.
2. Click Save tools.

Add an MCP server

1. Under MCP servers, click + Add MCP server and fill in a name (letters, numbers, underscore), the server's https URL, and, if the server needs one, an auth header or query key (e.g. header Authorization, value Bearer {{secret}}, plus the key).
2. Click Save tools. Backprompter connects to the server and lists its tools on the server's card — or shows why it couldn't connect. Use Refresh tools to list them again later.

Public servers such as https://mcp.deepwiki.com/mcp (questions about GitHub repositories) need no key, and make a good first test.

Give an agent its tools

In the agent editor, open the Tools dropdown and tick what this agent may use, then save the agent. For an MCP server you can tick:

• All tools — the agent gets whatever the server offers when it runs. Tools the server adds later reach the agent within about 5 minutes, with no change on your side.
• Individual tools — only those. If the server later removes one, it drops out and the picker shows it as not currently offered.

Data-Analysis Agents (Code Execution)

Set an agent's Artifact Type to Code Execution to build a data-analysis agent. Instead of answering in prose, the agent writes JavaScript that runs in a secure in-browser sandbox over CSV data you attach, and the computed answer is shown.

1. Set Artifact Type to Code Execution (JS over CSV data) and save the agent.
2. In the chat, click Data (CSV) to attach one or more CSV files — each becomes a named dataset.
3. Ask a question (e.g. “total revenue by region”). The agent generates code, it runs over your data, and the result appears in the artifact pane.

Testing Agents

Mock Users

Mock users let you test how an agent responds to different user personas without needing real users. Each mock user has a name, a short summary, and a longer detailed profile that gets injected into the agent's context.

1. Click + next to Mock Users in the sidebar.
2. Fill in the name, summary, and profile fields.
3. Click Save. The new mock user is selected straight away.

Every app also has a built-in Default user, first in the dropdown and selected whenever no other mock user is: "A user of <your app> - <your app's description>". It's built from the app's name and description, so a clear description gives your tests better context. It isn't saved and can't be edited or deleted.

User Simulation

The Simulate User action in the sidebar's Actions section runs an automated multi-turn conversation. The platform will generate synthetic user messages based on the selected mock user's profile — or the Default user's — and send them to the current agent automatically (up to 4 turns by default). The simulated user knows your app's name and description and keeps to what the app is for. This is useful for quickly stress-testing an agent without typing manually.

Evaluation

After a conversation, click Evaluate to open the evaluation modal. You can:

• Select the agent you were testing as the Target Agent.
• Choose the Evaluator Agent. The default, Default evaluator (built-in), gives a score out of 10 and a short list of justifications, and needs no setup. You can pick one of your own agents instead, for an evaluator with its own criteria.
• Click Run Evaluation to have the evaluator score the conversation automatically. It's given the target agent's instructions and its settings — model, web search, documents, tools — so it judges the agent against what it could actually do. It also sees what each reply actually drew on: the web pages it cited, the tools it called, and the documents it retrieved. So it judges from the record instead of guessing whether, say, a search happened, and doesn't mark an agent down for skipping web search on a reply that didn't need it.
• Add your own Human Feedback text and a Rating (0–10).
• Click Save Evaluation to store it for later review.
• Use Suggest System Prompt Updates to let the evaluator propose prompt improvements. Show Diffs compares the suggestion with the current prompt, and Apply Suggestion (from either view) saves it to your editing copy of the agent, just as if you had edited the prompt yourself, so your next test chat uses it.

All saved evaluations are viewable via View All Evaluations in the Actions section. The table is sortable and filterable.

If the app's owner has set evaluation rules in Team Policies, every evaluator follows them — the built-in one and any evaluator agent.

Agent Versions

Every time you edit an agent and click Test Now, an editing version is created automatically. You can also create explicit snapshots at any time.

• Click Versions in the agent actions to open the Versions modal.
• Select any version to view its metadata and system prompt.
• Use Load Selected Version to restore a version for further editing.
• Use Promote to Default to make a version the active one for the agent.
• Use Compare Prompts (from the edit modal) to diff any two versions side-by-side.

Agents can be downloaded as JSON (⬇️ button) and re-uploaded (⬆️) to the same or a different app.

Files & RAG

Upload files to an app so agents can retrieve relevant content at query time (Retrieval-Augmented Generation).

1. Click 📁 Files in the app actions bar.
2. Upload files (text, PDF, Office docs, code) or fetch a URL.
3. Select one or more files, choose or create a Collection, and click Index for Search.
4. On the agent, set RAG to Knowledge Base and choose the collection.

Files can also be attached directly to a single message using the Attach Files button in the chat composer.

Voice Chat

Backprompter supports real-time voice conversations using Deepgram's streaming speech-to-text and text-to-speech. Click the Voice button in the chat composer to start a voice session. The voice status indicator at the bottom of the chat pane shows the current state (idle, listening, speaking).

Inviting Teammates

You can invite other people to build on an app with you. Everyone uses their own Backprompter account — there is no shared password, and each person's edits are kept in their own working copy, so two people editing the same agent never overwrite each other.

Every app has one owner (whoever created it). Everyone invited is an editor.

To invite someone, select the app and click 👥 Team, then enter their email address. You can have up to 10 teammates per app; pending invitations count toward that limit, so removing someone frees a seat. An editor can leave an app at any time from the same panel.

If the address already has a Backprompter account, access is immediate. If not, the invitation waits — and they must sign up with the address you invited, because that is how it is matched. They also get an invitation email with a link to accept; opening it and signing in brings them straight into the app, whether they sign up with Google or with an email and password. Replying to the email reaches you directly.

Team Policies

As the owner, you can set rules that every agent in the app must follow, whoever built it. Select the app and click 🛡️ Policies (owners only — editors don't see the button or the rules). There are two boxes; fill in either, both, or neither:

• Guardrails for all agents — e.g. "Never give legal or medical advice. Never share customer personal data." They apply to every agent run: in the builder, the deployed chat, the API, Slack, voice and MCP clients.
• Rules for evaluations — how evaluations must be done, e.g. "Deduct points for any answer not grounded in the app's documents." They apply to every evaluation, with the built-in evaluator or an evaluator agent a teammate made, on top of the guardrails.

Backprompter adds your rules to the start of each agent's prompt on the server, marked as taking precedence over the agent's own instructions, its documents, and anything asked in the conversation. Where an agent's instructions conflict with them, your rules win. Boxes you leave empty add nothing at all.

Billing & Credits

Backprompter has two plans. See the Pricing page for the full rate table; this is the short version.

Plans

• Hobby (free) — a free account can't create apps or agents, or run agents, of its own. It can work on someone else's app when a Dev Pro account invites it; the app's owner pays for that work. To build your own apps, upgrade to Dev Pro.
• Dev Pro ($5 / month) — for shipping to real users. Unlimited agents and messages, production API keys, deployed chat UI, SDK integration, and voice. Beyond the monthly fee, usage is pay-as-you-go, drawn from your credit balance.

Sign up with a permanent email address: disposable and temporary-mail addresses are refused.

Credits & pay-as-you-go

Dev Pro usage is charged against a prepaid credit balance shown in the billing badge in the app header. You top up credits from the billing panel. Charges include a per-call orchestration fee, the model's API cost plus a service markup, and storage for app configuration and RAG documents. Exact rates are on the Pricing page.

Two builder helpers, Suggest System Prompt Updates and the Backprompter Copilot, are charged for their model cost only, with no orchestration fee. Both are charged to the owner of the app you have selected, like any other work on the app, and use the app's BYOK key when it has one. When the copilot searches the web, the search fee (about $0.01, at most two searches a question) is part of that cost. With no app selected — before you have built one — copilot questions are charged to you.

API Access

You can call any agent from your own backend without using the Backprompter UI. Full details are available in the auto-generated API Reference for each app:

1. Select an app in the sidebar.
2. Click 🔌 API in the app actions bar to open the API Reference page.
3. To authenticate server-to-server requests, go to 🚀 Deploy and click Generate API Key. Pass the key as the x-bp-api-key header.

The API Reference page documents every endpoint and shows live example payloads tailored to your app's agents.

Your app's keys are listed under API access in the 🚀 Deploy dialog, with when each was created and last used. Click Revoke to switch one off for good — anything still using it (a server, an MCP client) stops working at once. An app can have up to 10 active keys; revoking one frees a slot. Only the owner can see, create or revoke keys.

Use Your Agents from MCP Clients

Backprompter is also an MCP server, so MCP clients — Claude Code, Cursor, Claude Desktop and others — can call your agents as tools. A client connects with one of your app's API keys and sees each agent you've exposed.

1. On each agent you want to offer, tick Expose via MCP and save the agent.
2. Create an API key under API access in the 🚀 Deploy dialog.
3. In the same dialog, open MCP server. It shows your MCP endpoint, the agents it currently offers, and ready-to-paste setup: a claude mcp add command for Claude Code, and a JSON config for Cursor and other clients that take a URL and headers. Replace YOUR_API_KEY with your key.

The key goes in an Authorization: Bearer <key> header (x-bp-api-key also works). Sign-in with OAuth isn't supported yet, so use a client that can send a header. For Claude Desktop, add the server through the mcp-remote bridge in its config file (Settings → Developer → Edit Config), then fully quit and reopen it:

"mcpServers": {
  "my-app": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "<your MCP endpoint>", "--header", "Authorization:${AUTH_HEADER}"],
    "env": { "AUTH_HEADER": "Bearer YOUR_API_KEY" }
  }
}

What the client sees

• Each exposed agent is one tool named <app>_<agent>, e.g. ApexAI_converse (letters, digits, _ and - only). Renaming the app renames its tools.
• The tool's description is the agent's Summary. Clients decide when to call a tool from its description, so say what the agent knows that the client's own model doesn't — your documents, your data — and when to use it. A vague summary means the agent rarely gets called.
• A call takes a message, and optionally a conversation of earlier turns. Each call is otherwise independent: the agent doesn't remember previous calls.

Deploying a Chat UI for End Users

Backprompter can deploy a hosted chat interface so your users can interact with your agents without needing access to the developer UI. The deployed UI is a separate, standalone web app.

1. Select the app you want to deploy.
2. Click 🚀 Deploy in the app actions bar.
3. Under Deploy a chat UI, configure the End-user login methods (see below).
4. Click Deploy UI.
5. Wait for the deployment to complete. A link to your live chat URL will appear.

You can re-deploy at any time to update settings (e.g. change auth modes or add new agents). Existing users are not affected until they refresh.

Auth Modes

Choose one or more methods your end users can use to sign in:

• Anonymous — users get a guest session automatically with no sign-up required. Best for open demos or public tools.
• Secret code — users enter a one-time secret key to gain access. Useful for invite-only products or beta testing groups (see Secret Keys).
• Email / password — users create an account with an email and password.
• Google — OAuth login with a Google account.

Secret Keys

When Secret code is enabled, click Generate Secret Key to create a new one-time access key. Secret keys are shown only once — copy and distribute them before closing the modal.

The keys table shows all existing keys with their creation date. You can revoke individual keys at any time using the Revoke action in the table.

Your Deployed URL

The deployed chat UI is hosted at:

https://bptr-chat.web.app/#/<your-app-id>

Share this URL with your end users. The #/<your-app-id> fragment ensures users land directly in the correct app.

Slack

Any app can also answer inside a Slack workspace, with no code and no separate deployment.

1. Select the app and click 🚀 Deploy.
2. In the Slack section, click Add to Slack and approve the install.
3. In Slack, invite the bot to a channel: /invite @Backprompter
4. Mention it (@Backprompter what are our refund rules?) or send it a direct message.

By default the meta-router picks the best agent for each message. You can pin a single agent instead from the same Slack section, and disconnect the workspace there at any time.

Charging Your End Users (Payments)

You can require end users to pay before they can use your deployed app. Backprompter uses Stripe Connect: you link your own Stripe account and payments settle directly into it — Backprompter takes no cut and never touches your customers' money. It only records who has paid and enforces access at run time.

Set it up

It's all done in the Backprompter UI — no code, and nothing to configure in the Stripe dashboard.

1. Open the Deploy modal for your app and go to Payments. Click Connect Stripe and authorize with your Stripe account (Stripe Connect onboarding).
2. Choose the Price to charge — your account's active Stripe prices are listed for you. Recurring prices become subscriptions; one-time prices grant lifetime access.
3. Enable the payment gate and save. That's it.

What end users experience

• When the gate is on, requests are blocked with a 402 Payment Required until the user pays.
• The hosted chat UI (and the SDK) surface a checkout link; after paying, access is granted automatically.
• Subscriptions are re-checked on each request — cancellations and expiries revoke access (with a short grace window); one-time payments grant lifetime access.

SDK Integration

Detailed guides for each deployment option.

Option 1 — Deploy a Chat UI (No Code Required)

The fastest path to production. Backprompter hosts a complete, polished chat interface for your end users — no frontend or backend code needed.

1. Build and configure your agents in the Backprompter UI.
2. Click 🚀 Deploy in the app actions bar.
3. Choose the login methods you want your users to see (anonymous, email/password, Google, or secret code).
4. Click Deploy UI. Within moments your app is live at:
   https://bptr-chat.web.app/#/<your-app-id>

Embed the hosted chat in your website

Because the hosted chat is a normal web page, you can drop it into any existing site with an <iframe> — no build step and nothing to host yourself. Replace <your-app-id> with your App ID (shown on the Deploy modal and the API Reference page).

Inline — embed the chat directly in the page

<iframe
  src="https://bptr-chat.web.app/#/<your-app-id>"
  style="width: 100%; height: 640px; border: none; border-radius: 12px;"
  title="Chat"></iframe>

Floating widget — a collapsible chat bubble in the corner

Paste this snippet before the closing </body> tag of any page. It adds a floating button that opens and closes the chat in an overlay.

<!-- 1. Floating button + hidden chat window -->
<button id="bpChatBtn" aria-label="Open chat" style="
  position: fixed; bottom: 20px; right: 20px; width: 60px; height: 60px;
  border: none; border-radius: 50%; background: #2563eb; color: #fff;
  font-size: 24px; cursor: pointer; box-shadow: 0 4px 12px rgba(0,0,0,.15);
  z-index: 9999;">💬</button>

<div id="bpChatWindow" style="
  position: fixed; bottom: 90px; right: 20px; width: 400px;
  height: 640px; max-height: calc(100vh - 120px); display: none;
  background: #fff; border-radius: 12px; overflow: hidden;
  box-shadow: 0 5px 24px rgba(0,0,0,.2); z-index: 9999;">
  <!-- Replace <your-app-id> with your App ID -->
  <iframe src="https://bptr-chat.web.app/#/<your-app-id>"
    style="width:100%; height:100%; border:none;"></iframe>
</div>

<!-- 2. Toggle logic -->
<script>
  (function () {
    var btn = document.getElementById('bpChatBtn');
    var win = document.getElementById('bpChatWindow');
    btn.addEventListener('click', function () {
      var open = win.style.display !== 'flex';
      win.style.display = open ? 'flex' : 'none';
      btn.textContent = open ? '✕' : '💬';
      btn.setAttribute('aria-label', open ? 'Close chat' : 'Open chat');
    });
  })();
</script>

Option 2 — Backprompter SDK on Your Own Frontend

Build your own custom UI while letting Backprompter handle authentication and agent calls. The SDK authenticates users through Backprompter's multi-tenant auth system, so users get persistent accounts and their data is scoped to your app.

Setup

<!-- 1. Include the SDK -->
<script src="https://cdn.jsdelivr.net/npm/backprompter-sdk/dist/backprompter-full.min.js"></script>

<script>
  // 2. Point the SDK at your app (find your App Key in the API Reference page)
  Backprompter.setAppKey('your-app-key');
</script>

Sign users in

// Email + password
await Backprompter.signIn(email, password);

// Anonymous (no sign-up required)
await Backprompter.signInAnonymously();

// Sign out
await Backprompter.signOut();

Call an agent

const result = await Backprompter.run({
  agentId: 'your-agent-name',   // omit to let the meta-router pick
  userPrompt: userMessage,
  conversationHistory,          // array of { role, content } pairs
  profileString,                // optional: personalise responses with a user profile
});

console.log(result.response);  // agent's reply

Full reference: Browser SDK Reference → — every method, with attachments, voice, conversation history, artifacts, custom data, vector search, and paid access.

Option 3 — Backprompter SDK on Your Own Backend

Call agents from your own server using a Backprompter API key. Your backend handles user authentication however you like; Backprompter never sees your users' credentials.

Generate an API key

1. Open the 🚀 Deploy modal for your app.
2. Click Generate API Key and copy the key — it is shown only once.

Install the server SDK

npm install backprompter-server-sdk

Call an agent

import BackprompterServer from 'backprompter-server-sdk';

const bp = new BackprompterServer({
  apiKey: process.env.BACKPROMPTER_API_KEY,
  tenantId: process.env.BACKPROMPTER_APP_KEY,
});

const result = await bp.run({
  agentId: 'your-agent-name',
  userPrompt: req.body.message,
  conversationHistory,         // array of { role, content } pairs
  profileString,               // optional: any user context you want to inject
});

res.json({ reply: result.response });

Full reference: Server SDK Reference → — every method, including per-user data storage with forUser(), identity tokens, API key scopes, and how payments behave on API-key calls.

Using Your Own Login

Options 2 and 3 are not exclusive. If your app already has a login, you can keep it and still give your frontend the full SDK. Your backend exchanges your own user id for a short session token. Your frontend signs in with that token. Backprompter never sees a password.

On your backend

// behind your own session check
app.post('/api/bp-token', requireMyAuth, async (req, res) => {
  const { customToken } = await bp.createUserToken({
    externalId: req.user.id,     // your own user id
    email: req.user.email        // a label for your dashboard
  });
  res.json({ customToken });
});

On your frontend

const { customToken } = await fetch('/api/bp-token').then(r => r.json());
await Backprompter.signInWithCustomToken(customToken);

// everything now works as a signed-in end user
await Backprompter.saveData('preferences', { theme: 'dark' });
await Backprompter.run({ agentId: 'analyst', userPrompt: 'Hello' });

Backprompter derives a storage id from your App Key and your external id, so the same user always returns to the same data. If you would rather keep every call on your server, use bp.forUser(yourUserId) from the Server SDK instead — see the Server SDK Reference.

Tutorials

Step-by-step walkthroughs for the most common Backprompter workflows. Open the Tutorials page →