AgentCloud Operator Guide

Open the console →

Running the white-label AI chat agent platform: tenants, agents, the embed, token billing, and the admin API. All other platform guides live at the guides hub.

1 · How it works

A tenant is the customer (an agency or a business). Tenants own agents - branded chatbots. Each agent has a public embed key; a client installs their bot on any website with one tag:

<script src="https://ai.worldvc.business/widget.js" data-agent="EMBED_KEY" async></script>

Visitors chat with the client's bot (their name, their colors - never a platform name). Replies stream from OpenAI; every reply's tokens are metered to the tenant - that's the billing trail.

The embed key is public by design (it sits in page source). It grants exactly one thing: chatting with that one agent. Admin actions all require the Bearer ADMIN_TOKEN.

2 · Onboard a client

  1. Console → Tenants → + New: slug (acme-agency) + display name.
  2. Agents → + New: pick the tenant, set the bot name, greeting, widget color, and instructions (the business knowledge: services, hours, what never to promise).
  3. Save → copy the embed snippet → client pastes it before </body> on their site.
  4. Verify with Try in demo (or /demo?key=…) before sending it out.

Config is hot: edits to greeting/instructions/color apply to the next widget load - no client-side changes ever needed again.

3 · Usage & billing

Every reply records input/output tokens per tenant + agent (ac_token_usage). The console's Usage tab (and GET /admin/usage?month=YYYY-MM) rolls up requests + tokens per tenant monthly. Price against your OpenAI cost per token with margin; the per-tenant rollup is the invoice line.

4 · Environment (Railway)

VarPurpose
OPENAI_API_KEYChat completions. Without it /chat returns 503.
DATABASE_URLPostgres (shared instance; all tables prefixed ac_).
ADMIN_TOKENBearer for /admin/* + console login. Separate token from the voice console's.
PUBLIC_BASE_URLShown in embed snippets (https://ai.worldvc.business).
OPENAI_CHAT_MODELDefault model (gpt-4o-mini); per-agent override in the console.

Health: GET /healthz → { ok, ai, store, admin }.

5 · Admin API

RouteDoes
GET/POST /admin/tenants · DELETE /admin/tenants/:idTenant CRUD (slug + name). Delete cascades to agents/conversations.
GET/POST /admin/agents · DELETE /admin/agents/:idAgent CRUD. POST with id updates; without creates (embed key generated server-side).
GET /admin/usage[?month=]Monthly token rollup per tenant.

Public (widget) routes: GET /widget-config/:key, POST /chat/:key (SSE), GET /widget.js, GET /demo.

6 · Troubleshooting

SymptomFix
No bubble appears on the pageCheck the browser console for [chat-widget] errors. Bad key → 404 from /widget-config; copy the snippet again from the agent card.
Bot replies "assistant is unavailable"/healthz - usually ai: missing OPENAI_API_KEY or an OpenAI-side error in the service logs ([chat] stream failed).
Console empty / 401Wrong or missing ADMIN_TOKEN; each engine (voice vs agents) has its own token.
Answers are genericThe agent's Instructions are the knowledge. Phase 2 (RAG: upload the client's real content) is the roadmap fix.