On the first login (and after any major-version bump of the Terms of Service or Privacy Policy) Sophia displays a blocking modal asking the user to accept three things:

The modal cannot be dismissed without accepting or logging out — any Mongo request issued before acceptance is intercepted server-side and returns 403 AcceptanceRequired. The acceptance record (version, URL, timestamp, IP address) is persisted on the user document under consents; see Legal Documents and Consents below.

Click New Agent and provide a unique ID (e.g. support, product-docs). The ID is used in the web URL path (/{agentId}) and in the MCP endpoint URL (/mcp/{agentId}/).

The system prompt template is interpolated at query time. Use the placeholder that matches your operating mode:

The template editor provides a live markdown preview. The editor also displays a cached prefix size and a cost-per-interaction estimate based on the chosen model.

Provide a newline-separated list of suggested questions. They appear as clickable chips at the start of a new chat session — clicking one sends it as the first prompt. Useful for guiding new users to common entry points.

Tags are the primary mechanism for knowledge segregation. The agent’s tags are ANDed with every vector search: only documents carrying all of the agent’s tags are retrieved.

The agent editor exposes these fields directly. The right-hand side shows a model picker with origin (EU/US), pricing per million input/output tokens, and a tool-use score that highlights models suited for agentic workflows.

Enable Agentic Mode on an agent to let Sophia operate as an autonomous agent: it iteratively calls tools (search, file retrieval, list-paths, list-tags) before composing a final answer.

When a user asks a question in an agent with Agentic Mode, Sophia:

Users see the agentic phase in real time when streamThinkingEvents is on — each tool call becomes a badge with name, arguments, and result summary; expanding it reveals the full breakdown.

When agenticContextManagement is enabled, Sophia replaces classic history injection with a persistent markdown context document keyed by chatId:

This frees the main loop from history-token cost on every turn and keeps long-session coherence. The prompt template should not instruct the model to call context_* itself — doing so blocks the synthetic flow.

Enable Collaborative Mode (under Agentic settings) to let the model render rich interactive HTML artifacts directly in the chat:

show produces HTML in an iframe injected into the chat — diagrams, calculators, mini-dashboards, REST micro-tools. PicoCSS v2 with dark theme is pre-loaded; the model can also use a <style> block for custom CSS.

ask is not available in the main loop. It is invoked only by the post-answer synthetic call, which constrains the model to attach 2–4 follow-up buttons. The prompt template should not instruct the model to call ask directly — doing so prevents the synthetic flow.

A per-message toggle in the chat UI lets the end user activate Collaborative Mode for a specific question, even on agents where it is off by default.

Set deckView: true to replace the linear chat layout with a horizontal deck of cards — each interaction becomes a swipeable card, prompt above, scrollable answer below. Useful for guided tours, lesson decks, and product demos.

The active agent is encoded in the URL path:

Use these URLs when embedding Sophia in an iframe:

For MCP clients, the agent is selected via the URL path (see Sophia MCP Server).

Set private: true to require authentication. Access is granted to:

Public agents work without authentication.

List all agents:

Create or replace an agent:

Update options only:

Delete an agent:

Apache Tika handles parsing for prose formats; code-aware splitters preserve semantic boundaries (functions, classes) for source files.

Click Upload to open the upload dialog.

The dialog supports:

After upload, documents are processed automatically:

Two viewing modes:

Filters: filename ($regex substring), tags (comma-separated, AND filter), failed-only (toggle that switches to flat view and isolates documents whose indexing failed).

Documents whose vectorization failed are flagged with a red ⚠ icon and a tooltip exposing the error message. A Retry button clears the failure flag and re-queues the document for processing. Common causes: malformed PDF, throttled embedding model, transient AWS errors.

Hover any document row to reveal a small ✎ icon next to the tag chips: click it to inline-edit tags for a single document. Press Enter to save, Escape to cancel.

For bulk operations use Batch Tags in the toolbar:

When in tree mode the dialog operates within the current directory; an Include subdirectories checkbox (on by default) controls whether the operation recurses. The status text under the input shows the active scope and tag/filename filters in effect. A progress bar appears during execution.

Deleting a document also removes all its text segments from the vector store. Bulk delete is supported via the REST API.

Upload a document:

List documents:

Filter by directory prefix:

Update tags on a single document:

Delete a document:

Two viewing modes (flat / tree). Each row shows source file, segment index, content preview, and tags. Expand a row to see the full segment rendered as raw text or markdown; a copy button copies the segment text.

The Semantic Search panel lets you test RAG retrieval directly against the knowledge base:

Useful for tuning relevantsLimit, debugging missing-document issues, and verifying tag filters.

There is no self-service signup. The only way for a user to enter the system is to receive an invitation from an administrator.

Tags are the primary mechanism Sophia uses to scope what knowledge an agent can retrieve, and to further narrow what a specific user can see within that scope. Understanding the three actors and how they combine is essential to grant access correctly.

A tenant-admin sees only resources whose tenant field equals their own. The isolation is enforced via RESTHeart’s mongoAclAuthorizer (readFilter + writeFilter + mergeRequest) and complemented by server-side interceptors for documents that the backend creates on behalf of the user (chats, segments, MCP sessions, API tokens).

To create a new tenant: open Admin > Tenants as a global admin, click New Tenant, and assign a tenant administrator. The global admin remains responsible for tenant CRUD; tenant-admins cannot manage tenants other than their own.

Every authenticated user (regardless of role) has access to /profile — a single self-service page exposing:

Administrators reach the page from the Profile link in the admin sidebar; regular users via the avatar at the top-right of the chat. Both entry points append a ?back=<currentUrl> query parameter, and the profile page’s ← Back button honours it — returning the user to the exact chat or admin section they came from. The fallback is /admin for administrators and / (the default agent) for regular users; the back target is ignored if it points to /profile itself (to avoid loops) or is not a same-origin path (for security).

The user-self PATCH is whitelisted at the ACL layer to password and name only — every other field (roles, tenant, agents, tags, agentTagRestrictions, notes) remains administrator-only.

When a user accepts (at activation or during re-acceptance), Sophia records three nested objects under users.<_id>.consents:

The unfairTermsAndConditions entry attests to the explicit approval of art. 1341 c.c. clauses listed in §13.5 of the Terms. The url field stores the exact versioned document the user accepted — an immutable audit reference.

The AcceptanceCheckInterceptor runs after authentication on every Mongo request. If consents.termsAndConditions.version or consents.privacyPolicy.version differs in MAJOR component from the configured current versions (or is missing), the interceptor replies with 403 and body { "error": "AcceptanceRequired", "policies": ["terms", "privacy"] }. The web client’s HTTP interceptor catches this response and opens the blocking acceptance modal.

API tokens are not exempt — they inherit the consents of the user who issued them. A major-version bump therefore blocks the token until the issuing user re-accepts via the web UI. To rotate an API token under a different user, revoke and re-issue from the API Tokens page.

MINOR changes do not require config changes nor re-acceptance: the URL is canonical, the content can be amended in place.

Click New Token and configure:

The JWT token value is shown only once after creation — copy it immediately. Token TTL is approximately ten years; use Revoke to invalidate ahead of expiry.

The MCP Config button next to each token generates ready-to-paste configuration snippets for Claude Desktop, Cursor, Claude Code, and VS Code, including the token in the Authorization: Bearer header.

See Sophia MCP Server for full setup details and the OAuth alternative.

Issue a new token:

Revoke a token:

Delete a token:

Sophia automatically falls back across a configured chain of secondary models on transient errors (throttling, rate-limits, brief outages). A circuit breaker tracks recent failures per model and skips models in cool-down. The user receives a model_fallback event that the chat UI renders as an inline notice; the conversation continues seamlessly.

The fallback chain is configured server-side per environment.