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.

1. Set Your Builder Identity

Before creating anything, select or create a Builder in the top section of the sidebar. Single account can share multiple builders. It allows you to collaborate and track versions by builder identity.

• Choose an existing builder from the dropdown, or
• Select + Create New Builder, type a name, and click Create Builder.

2. 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.

3. 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 mid-conversation. Define tools once at the app level, then tick the ones each agent may use (see API Tools).
• Routable through meta-router — makes this agent a candidate when the meta-router automatically selects an agent from your app (see Meta-Router).
• 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.

API Tools

API tools let an agent call an external HTTPS endpoint during a conversation to fetch live data (e.g. exchange rates, a product lookup). You describe in natural language when to use it; the model decides to call it, Backprompter runs the request on the server with your stored key, feeds the result back, and the agent answers.

1. In the agent editor, under Tools, click Manage app tools….
2. 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.
   • URL — 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 or path.
   • Auth — optional header or query key. The secret is stored encrypted and never sent to the model or browser.
3. Click Save tools. Back in the agent editor, tick the tools this agent may use, then save the agent.

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, then select the mock user from the dropdown before chatting.

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 and send them to the current agent automatically (up to 4 turns by default). 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.
• Select an Evaluator Agent — an agent whose job is to score conversations.
• Click Run Evaluation to have the evaluator agent score the conversation automatically.
• 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.

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

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).

Billing & Credits

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

Plans

• Hobby (free) — for exploring and prototyping in the builder UI. Includes up to 2 agents, and a one-time lifetime allowance of 50 test messages or $1 of model usage (whichever comes first). Deploying a chat UI, the production API/SDK, and voice chat are not included.
• Dev Pro ($3 / 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.

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.

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.

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.

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

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 });

Tutorials

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