Building Apps

The page runs in the visitor's browser and is hosted as static files on your own address. It has no server of its own. Anything that needs a backend (reading data, calling a model, calling another service) is done by an agent, and the page reaches the agent through botspot.run(role, input).

A role is a name your page uses, such as assistant or scientist. In Workbench you bind each role to one of your agents. The page never holds an API key: the server resolves the role to the agent, runs it, and bills the right wallet.

So server routes, server actions and secrets inside the page are outside the model. If the page needs a secret or a third-party call, put it in the agent and let the agent do it.

1. In Workbench, open Apps and create an app, or open an existing one.
2. Bind a role to an agent in the app's workflow binding. Use a short, lowercase role name.
3. Check what the agent expects as input (see The input contract). This is the step people skip.
4. Call botspot.run from the page with exactly those inputs.

import { botspot } from './botspot.js';

// The agent bound to the role "scientist" has a Big Text input named "scientist"
// and a Big Text input named "question". Send them by name:
const res = await botspot.run('scientist', {
  scientist: 'Marie Curie',
  question: 'What did you learn from radium?',
});

res.output;        // the reply, always a string
res.data;          // the reply parsed as JSON, only when it is JSON
res.bics_charged;  // what this run cost

If you use the App builder, it is told each bound agent's inputs on every request, so it writes the call with the right keys. You can still read the contract yourself when you write the call by hand.

botspot.run(role, input) returns a promise for { ok, role, output, data?, bics_charged }.

What you can pass as input.

• An object, such as { scientist: "Marie Curie" }. Each key fills the input of that name. This is what you want for almost every agent.
• A string. It is wrapped as { text: "…" }, and only a Chat Input reads that key. A Big Text input named scientist will not see it.

// A plain string reaches ONLY a Chat Input.
await botspot.run('assistant', 'hello');
// is sent as { text: 'hello' }

If a visitor is not signed in, botspot.run sends them to the hosted login and the page navigates away. It does not resolve in that case.

Every agent has a list of inputs it reads. A required input that the page does not send makes the run fail inside the workflow, which the page otherwise sees only as a failed request. The contract tells you the names up front.

GET /agent/v1/workflow/agents/{agent_id}/input-contract

{
  "agent_id": "78f30519-…",
  "inputs": [
    {
      "key": "scientist",
      "node_id": "n_3",
      "type": "input.bigtext",
      "kind": "text",
      "required": true,
      "label": "Scientist",
      "also_accepts_text": false
    }
  ]
}

The contract is read from the same release that a run would use, so it cannot drift from what the agent actually does. It is limited to your own workspace's agents and needs an authenticated workspace call; a visitor's page cannot read it.

How the agent finds a value. Each input looks in this order: a nested entry under its node id, a nested entry under its name, then a top-level key by id, then by name. Sending by name is the simplest.

A failed call throws an Error whose message is the cause. Show it.

try {
  const { output } = await botspot.run('scientist', input);
  show(output);
} catch (err) {
  // err.message is the real cause. Show it. Do not replace it with sample text.
  showError(err.message);
}

Development and published apps differ on purpose. On a development app the workspace is the one looking at the page, so the error carries the readable cause above. On a published app the person looking is a customer, so they get a plain status instead of your agent's internals.

When a botspot.run call from a development app fails, Workbench records it and shows a banner above the preview: what went wrong, what the page sent, and what was missing. Only key names are kept, never the values a user typed.

• The banner lives in the Workbench builder. The standalone preview address does not show it.
• It shows the newest failure from the last 15 minutes and refreshes every few seconds.
• Fix with AI hands the cause to the builder. It is a button, not automatic, because the fault can be in the agent rather than the page, and an unattended loop would spend your BICS.
• Published apps are not recorded this way.

Published apps show a small BICS balance pill with a top-up popup, added for you. It is not shown on development hosts, because the balance there would be the wrong number.

Until the last two ship, keep files and records in an agent: a workflow with a data node reads and writes your connected database, and the page gets the rows back in data.

• Upload a zip, or connect a public git repository. BotSpot builds it and hosts the files at your-slug.botspot.app.
• Development apps run on a separate development address, open only to workspace members.
• The build supplies the app id and API address to the SDK. No key reaches the browser.
• Rebuilding is manual for now: push your change, then rebuild the release.