Build your agent
Agents
An agent is the embeddable unit — persona, prompt, knowledge, theme, rules — that runs on a customer's site. This page covers creating, configuring, publishing, and rolling back agents.
Create an agent
From the customer app: /app/agents → New agent. You'll be
asked for a name and default language. Everything else has sensible
defaults you can refine later.
On signup we also auto-create a starter agent named after your domain. You can rename, replicate, or delete it freely.
The agent record
Every agent has these editable fields:
| Field | What it does |
|---|---|
name | Display name in the dashboard. Not shown to visitors. |
language_default | BCP-47 / ISO 639 code that pins the agent's reply language. Picks any locale auto-discovered from lang/*.json (132 ship out of the box; en/es/fr/tr are fully translated, others have UI chrome translated). Used when the visitor's Accept-Language doesn't match — the agent can also override per-conversation. Empty = follow the visitor's browser locale. |
persona | JSON: { name, tone }. Tone goes into the system prompt verbatim. |
theme | Widget colors, radius, position, launcher label. |
system_prompt | Optional override. Appended to the built-in prompt — doesn't replace the safety / RAG instructions. |
guardrails | JSON: { avoid: [topics], max_chars }. |
starter_prompts | Up to 6 chips shown above the input on first open. 80 chars each. |
confidence_threshold | 0–1. Below this score (after rerank) the agent says "I don't know" instead of guessing. |
allowed_origins | Strict list of scheme://host origins where the widget may load. |
auto_index_visited_pages | If on, pages visitors land on get queued for crawl + index. |
Confidence threshold
The retriever scores every chunk against the visitor's question. Anything
below confidence_threshold is dropped. If fewer than two
chunks survive, the answer is flagged low_confidence and the
agent answers honestly that it doesn't know — and the system queues a
"knowledge gap" entry you can review.
Defaults are tuned per provider:
- Cloudflare bge-base-en-v1.5 embeddings — default
0.5. Cosine scores run lower than OpenAI's, so the bar is lower. - OpenAI text-embedding-3-small — default
0.78. Set this on signup if you switch providers.
Draft → Published
Editing an agent never affects live visitors. The widget runtime reads
from a snapshot called agent_version. Clicking
Publish writes the current state to a new version and
points the agent's published_version_id at it.
Versions are immutable. To revert, open the agent's history and click Roll back on a previous version — that just updates the pointer. Nothing is deleted.
Embed the agent
The agent's settings page shows a one-line install snippet with your
data-agent-id baked in. The widget URL includes a
cache-busting hash that mutates whenever the bundle is rebuilt, so
customers don't get stuck on stale versions. See
Install snippet for details.
Multiple agents per workspace
You can run as many agents as you want — one for marketing, one for the help center, one for the in-app upsell flow, etc. Each has its own knowledge base, persona, and embed snippet. Conversations and leads stay scoped to the agent that handled them.