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. |
restricted_paths | Per-origin path blocklist — paths the widget refuses to render on even when the origin is in allowed_origins. Set to suppress the bar on checkout, account, or admin paths where a sales widget would feel wrong. See Allowed origins. |
auto_index_visited_pages | If on, pages visitors land on get queued for crawl + index. |
lead_prompt_strategy | When the bot offers to capture a lead. Today: after_n_turns (default), on_intent, off. Lets you tune capture aggressiveness per agent. |
wp_integration (JSON, encrypted) | WordPress / WooCommerce companion-plugin context. Stores the shopper-signing secret and any per-store config the LLM tools (e.g. lookup_order) need. Populated automatically when the WordPress plugin connects via API token; not edited by hand. |
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.
Delete an agent
Two ways to remove an agent:
- From the Agents index page (
/app/agents): hover any row, click the trash icon next to the gear in the Settings column. Confirm in the prompt and the agent is gone. - From the agent detail page (
/app/agents/{id}): click the destructive Delete button in the danger zone, confirm in the dialog.
Deletion is a soft-delete — the agents.deleted_at column
is stamped and the row is hidden everywhere downstream
(Inertia listings, embed, hot path). Sources, conversations,
leads, and the widget embed for that agent stop working immediately.
Recoverable manually via Agent::withTrashed()->find($id)->restore()
until the database janitor runs (today there is no auto-purge of
trashed agents — they live forever for accidental-delete recovery).
Authorization: requires owner, admin, or editor role on the workspace. Viewers and members of other workspaces hit a 403.
Bulk delete agents
Select multiple rows on the Agents index page (/app/agents)
via the checkbox column. The header checkbox toggles all rows on
the current page; shift-click a row checkbox to range-select between
the last clicked row and the current one. Selection persists across
pages until you click Clear.
A sticky bar at the bottom of the page surfaces the count and a
Delete action. Confirm in the prompt — every
selected agent is soft-deleted in a single transaction. Cross-workspace
ids are silently dropped from the result (the per-row policy gate
rejects them without leaking existence). Same workflow on
/app/workflows for bulk workflow delete.
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.