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:

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 hard delete. Buyer report 2026-05-19: soft-delete left phantom playground conversations + child DB rows visible after the customer "deleted" their agent, so the destroy path now calls forceDelete(). Every child row cascades via FK at the database layer: conversations, messages, leads, sources, documents, chunks, experiments, visitor_page_views, etc. The widget embed snippet for the agent stops resolving immediately.

The vector store (Cloudflare Vectorize / Qdrant) is not on the same DB connection, so DB cascade can't reach it. Destroy queues PurgeAgentVectorsJob just before forceDelete(): the job calls QdrantClient::deleteByFilter with ['agent_id' => $id] against the services.vector_collection index. It's idempotent and swallows transport errors so a temporary Vectorize outage doesn't block the user-facing delete. The php artisan vectors:audit reconciliation pass catches any leftovers from a failed purge.

Because the delete is permanent, there's no withTrashed() restore path. The platform-admin destroy at /admin/agents/{id} uses the same semantics (audit 2026-05-30) — it previously left soft-deleted rows that the customer couldn't see, defeating the orphan-cleanup intent the super_admin action was added for.

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 hard-deleted (same semantics as single-agent destroy: DB cascade reaches child rows; PurgeAgentVectorsJob queued per agent to clean Vectorize). Cross-workspace ids are silently dropped from the result (the per-row policy gate rejects them without leaking existence).

The same useBulkSelection hook + BulkActionsBar component now power bulk delete on every index page across the app:

• /app/agents — bulk delete agents (this page).
• /app/workflows — bulk delete workflows.
• /app/conversations — bulk delete conversations.
• /app/inbox — bulk delete captured leads.
• /admin/agents — super_admin bulk delete agents across workspaces.
• /admin/leads — super_admin bulk delete leads.
• /admin/conversations — super_admin bulk delete conversations.
• /admin/workspaces — super_admin bulk soft-delete workspaces (cannot delete the workspace you're currently signed into).
• /admin/users — super_admin bulk soft-delete users (skips self, last super_admin, and workspace owners).

Selection model is identical on every page: header tri-state checkbox, shift-click range select on row checkboxes, persistent selection across pagination, sticky bar with count + Delete + Clear. Each bulk endpoint accepts { ids: string[] } (max 100 per request) and runs every id through its resource's policy gate.

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.