Sophia is an AI-powered knowledge base assistant built on top of RESTHeart Cloud. It turns static documentation — PDFs, Markdown files, HTML pages — into a conversational agent that answers questions accurately, citing the source documents it draws from. Under the hood it uses RAG (Retrieval-Augmented Generation) combined with large language models (Claude by Anthropic, Amazon Bedrock) to find and synthesize relevant content from your knowledge base.
Sophia is available as a managed feature of RESTHeart Cloud. You can try it live on the RESTHeart documentation assistant or on the Italian tax law assistant powered by Agenzia delle Entrate documents. If you want to set up your own instance, head to the RESTHeart Cloud console.
March 2026 was a packed month: two major development threads — agent cost optimization and a new vision for human-AI interaction through interactive artifacts.
Interactive Artifacts and Collaborative Mode
The most significant addition this month is collaborative mode: a paradigm shift in how Sophia interacts with users.
The starting assumption is that Sophia's users are not people who "don't understand the domain." They are often experts — tax professionals, engineers, lawyers — who use the agent to speed up their own analysis. Traditional agents are monologues disguised as dialogue: they receive input, process it, produce output, without ever involving the user in the reasoning. Sophia can do better.
render_input and render_output
Two new tools — render_input and render_output — allow the agent to generate interactive HTML components directly in the chat.
render_output is used when a visual response is more effective than text: comparison tables, charts, dashboards, cards with highlighted key points. It is pure output, self-contained.
render_input is used in collaborative mode when the agent wants to gather context before proceeding: choosing between sources, multi-step wizards, structured clarification questions. The user's response returns to Sophia via sendPrompt() — a JavaScript function injected into the iframe that communicates to the parent via JSON-RPC 2.0 over postMessage, the same protocol used by Claude.ai.
Each artifact is rendered in a sandboxed iframe with a pre-injected base context: PicoCSS for automatic styling of semantic HTML elements (dark mode included, no CSS classes to document), vanilla JS, and a sophia.fetch() function for authenticated calls to RESTHeart directly from the browser using the session cookie.
Per-interaction control
Collaborative mode must be enabled by the administrator at the context level. When active, users see a toggle in the input area that can be switched on or off message by message — it is not a global chat state.
Streaming and sharing
Artifacts are rendered in streaming: HTML content arrives as deltas and is updated in-place inside the iframe without reloading the page. Each artifact has a share link with access control: users not authorized to access the context cannot view the artifact.
Steps-based architecture
The streaming model has been rewritten: interactions now use an array of steps instead of a flat array of chunks. Each step corresponds to a phase of the agent loop (search, reasoning, tool call, inter-tool text, artifact) — easier to display and navigate in the frontend.
Agent Cost Optimization
Compact search
The knowledge base search now returns short previews (150 words) alongside the precise document reference, instead of the full text. The agent autonomously decides which documents to retrieve and fetches them only when needed, significantly reducing token consumption per response. This option is configurable from the administration interface for each context.
Paginated document retrieval
Document retrieval is now organized into pages (page 0, page 1, …). The model navigates documents sequentially, replacing the previous chunk-based system that required coordination between index and length.
Document memory across interactions
During a conversation, the agent remembers documents already retrieved in previous responses, avoiding redundant downloads when the user asks related follow-up questions in the same chat.
Prompt caching
The system prompt and tool definitions are now transmitted in optimized form to reduce the cost of repeated model calls. Active support for compatible Claude Anthropic models.
Security and Authentication
Private contexts
A context can be marked as private. Access to chats and MCP tools requires explicit authentication and authorization. Unauthenticated users receive a 403 error; the web app redirects them to the login page preserving the destination URL, and automatically returns them to the requested context after authentication.
Access is also denied when the user's JWT tags do not intersect the context's tags — a filter that allows restricting access to subgroups of authenticated users.
OAuth 2.1 with PKCE
Sophia now supports the OAuth 2.1 Authorization Code + PKCE flow, compatible with clients like Claude Desktop. The server exposes the standard authorization and token endpoints, and publishes discovery metadata per RFC 9728 (.well-known/oauth-authorization-server): compatible clients complete authentication without any manual configuration.
JWT management and MongoDB authentication
Authentication is based on JWTs signed and issued directly by Sophia, with centralized issuer and signing key configuration. The backend uses RESTHeart's MongoDB realm for credential verification.
User management in the admin panel
New section in the administration panel for user management: listing, creation, and per-context access control.
API tokens
Complete overhaul of token management: from user-bound tokens to dedicated API tokens, with tag selection at creation time and a dedicated administration interface.
Cost and Usage Tracking
Cost dashboard
New section in the administration panel to explore costs at different levels of detail:
- Daily aggregates with a bar chart
- Per session (chatId): cost, number of interactions, date
- Per interaction: drill-down with details for each question/answer within a session
Sessions are ordered by date (most recent first) and filtered to exclude zero-cost sessions.
Per-user and per-MCP session tracking
Chats are now associated with the authenticated user. Token usage is recorded for MCP sessions as well, with the same granularity as web sessions.
Token usage in chat
Each assistant response shows the number of tokens consumed (input, output, embedding). A session summary at the bottom of the conversation displays total tokens and estimated cost.
MCP (Model Context Protocol)
Native Streamable HTTP transport
The MCP server has been rewritten with a native Streamable HTTP transport for Undertow, removing the dependency on external libraries. The server now supports GET, POST, and DELETE on MCP endpoints, with graceful shutdown of providers when the application closes.
MCP sessions are now stateless with auto-recovery: when a client uses a stale session ID (e.g. after a server restart), the server automatically recovers the session without requiring a new explicit initialization.
Authentication for private contexts
The MCP server verifies the client's identity via JWT before exposing a context's tools. The OAuth 2.1 + PKCE flow makes integration with Claude Desktop fully automatic: the client discovers the endpoints via the discovery document and completes authentication without manual configuration.
MCP configuration in admin
The context list in the administration area now shows a dedicated button to view the MCP configuration for each context: the endpoint URL and instructions for connecting the client.
Web Interface
- Internationalization: the web app now supports Italian and English
- Responsive sidebar in the administration panel
- Agent event display: agent loop steps (tool calls, searches, reasoning) are now shown with labels and improved formatting
- WebSocket recovery: the chat automatically reconnects on disconnection (visibility change, network timeout), with a dedicated UI showing reconnection status
- Tree view for documents and segments in the administration area, with pagination
In Progress
A new MCP tool — agent memory — is being specified. It will allow the agent to save and retrieve persistent information tied to the user across different sessions.
Also in progress: a spec for document source linking in responses, so each statement from the agent can be traced back to the source document and the specific section it came from.
Ready to Build Something Great?
Focus on what makes your app unique. Your backend is ready in minutes. Start with our free tier - no credit card required.