Exploring the WebUI Entrypoint in Solace Agent Mesh
A note on naming: In earlier versions of Solace Agent Mesh, entrypoints were referred to as “gateways.” You may still see the term “gateway” in some config files, directory names, and documentation. Going forward, the official term is Entrypoint. This post uses “Entrypoint” throughout.
The Solace Agent Mesh (SAM) is a framework for building and orchestrating collaborative AI agents that communicate through the Solace Event Broker. But agents on their own aren’t much use without a way for humans to interact with them. That’s where Entrypoints come in — and the WebUI Entrypoint is the primary, built-in way to talk to your agents through a browser.
The WebUI Entrypoint is a Python-based component built on FastAPI. You can find the source in the http_sse directory of the OSS repo.
In this post, we’ll walk through what the WebUI Entrypoint offers, how to get it running, and the features that make it more than just a chat window.
What is the WebUI Entrypoint?
The WebUI Entrypoint is a FastAPI-based backend bundled with Solace Agent Mesh. It bridges HTTP requests from your browser to the A2A (Agent-to-Agent) protocol running over the Solace Event Broker, and streams responses back in real-time using Server-Sent Events (SSE).
At a high level, the flow looks like this:
Browser <--> FastAPI + SSE <--> Solace Event Broker <--> Your Agents
The WebUI is not just a thin chat layer — it’s a full-featured workspace with session management, file handling, speech capabilities, project contexts, and more.
Configuration
The WebUI Entrypoint is highly configurable through its YAML config file. Here are the key areas:
Host and Port
The WebUI serves a React frontend accessible at http://<FASTAPI_HOST>:<FASTAPI_PORT> (e.g. 127.0.0.1:8000 by default). Both are configurable via environment variables as flat keys under app_config:
app_config:
fastapi_host: ${FASTAPI_HOST, 127.0.0.1}
fastapi_port: ${FASTAPI_PORT, 8000}
For the full configuration reference, see the WebUI Entrypoint docs and GitHub examples.
Feature Flags
Every major feature can be toggled on or off via frontend_feature_enablement:
frontend_feature_enablement:
speechToText: true
textToSpeech: true
background_tasks: true
projects: true
promptLibrary: true
projectIndexing: true
chatSharing: false # Requires identity_service + SQL
binaryArtifactPreview: false # Requires LibreOffice
auto_title_generation: true
This lets you tailor the UI to your needs — run a minimal chat interface or enable the full workspace experience.
Frontend Customization
Personalize the look and feel:
frontend_welcome_message: "Hi! How can I help you today?"
frontend_bot_name: "My Agent Mesh"
frontend_logo_url: "https://example.com/logo.png"
frontend_collect_feedback: true
Session Persistence
Choose between ephemeral and persistent storage:
session_service:
type: "sql" # "sql" for persistent
database_url: "${WEB_UI_GATEWAY_DATABASE_URL, sqlite:///webui-gateway.db}"
default_behavior: "PERSISTENT"
or
session_service:
type: "memory" # "memory" for ephemeral
SQL persistence unlocks projects, prompt library, background tasks, and sharing. For quick experimentation, memory mode keeps things lightweight.
Authentication
The WebUI supports optional OAuth2 authentication:
frontend_use_authorization: false # Set to true for OAuth2
external_auth_service_url: "https://..."
external_auth_provider: "generic" # or "azure"
In community mode (default), authentication is disabled and a default development user is used.
Getting Started
If you’ve already set up a Solace Agent Mesh project, the WebUI Entrypoint is ready to go. Your project will have an entrypoint config at configs/gateways/webui.yaml that references the shared broker and model configuration.
To start the WebUI along with your agents:
sam run configs/
Or to run just the WebUI Entrypoint:
sam run configs/gateways/webui.yaml
Once running, open your browser to http://<FASTAPI_HOST>:<FASTAPI_PORT> (e.g. http://localhost:8000 by default) and you’ll see the chat interface.
Feature Walkthrough
1. Chatting with Agents
The core experience is a conversational interface where you send messages to agents and receive streaming responses. When you type a message, the WebUI:
-
Submits the message as an A2A task to the Solace broker
-
Opens an SSE connection to stream the agent’s response in real-time
-
Renders the response as Markdown with support for code blocks, tables, and more
You can select which agent to talk to from the available agents in the mesh.
Agent discovery happens automatically — any agent that publishes an agent card on the broker becomes selectable in the UI. This means as you deploy new agents, they appear in the WebUI without any configuration changes.
Note on RBAC: Agent visibility in the UI depends on your Role-Based Access Control (RBAC) configuration. If RBAC is enabled, users will only see agents they have been granted access to. Make sure your RBAC policies are configured correctly so that the right agents are visible to the right users. See the RBAC documentation for details.
The streaming architecture means you see responses as they’re generated, not after the agent finishes thinking. Because the WebUI Entrypoint sits on top of the Solace Event Broker, it leverages the broker’s pub/sub messaging, guaranteed message delivery, and Solace queues to provide resilience. If an SSE connection drops, the WebUI can reconnect and replay missed events — the broker acts as a shock absorber, ensuring no lost responses.
2. Sessions
Every conversation in the WebUI lives inside a session. Sessions let you maintain separate conversation threads with full history, so you can context-switch between conversations without losing progress.
Key session capabilities:
-
Create and switch between multiple conversations
-
Search across sessions by name or content
-
Auto-title generation — the WebUI can use the LLM to generate a descriptive title for your session based on the conversation content
-
Persistent storage — with SQL-backed session storage (
session_service.type: "sql"), your sessions survive server restarts
Each session scopes not just the conversation history but also artifacts and agent context, keeping your work organized.
3. Projects
Projects take organization a step further. A project is a workspace where you can:
-
Upload context files (documents, data, code) that get passed to the agent alongside your messages
-
Set a system prompt that shapes how the agent responds within that project’s scope
-
Organize sessions under a project for grouping related conversations
-
Export and import projects as ZIP archives for sharing or backup
For example, you could create a project called “Q1 Sales Analysis,” upload your sales data files, set an instruction like:
You are a data analyst focused on quarterly trends.
Every conversation in that project automatically has that context. When you add new files to the project, existing sessions are notified of the additions.
Projects require SQL persistence to be enabled in the entrypoint config:
frontend_feature_enablement:
projects: true
session_service:
type: "sql"
4. Prompt Library
The Prompt Library lets you create, organize, and reuse prompt templates across sessions. Instead of retyping or copy-pasting complex prompts, you save them once and use them anywhere.
You can trigger saved prompts by typing / in the chat input, which brings up a list of available prompts to select from.
Features include:
-
Prompt groups for organizing templates by category or use case
-
Version history — track how your prompts evolve over time
-
Sharing with roles — share prompt groups with other users as owner, editor, or viewer
-
AI-assisted refinement — use the LLM to help improve and refine your prompts
-
Export and import for portability
This is especially useful for teams standardizing on prompt patterns — create a shared group with your best-performing prompts and let everyone benefit.
frontend_feature_enablement:
promptLibrary: true
5. Artifacts
Artifacts are files — both the ones you upload and the ones agents create for you. The WebUI handles both directions:
Uploading files to agents:
-
Upload files directly in the chat interface
-
Files are stored in the session’s artifact space and passed to the agent as context
-
Supported formats include documents, images, data files, and more
Receiving files from agents:
-
Agents can create and return files (charts, reports, generated code, etc.)
-
Download agent-generated artifacts directly from the chat
-
Binary artifact preview — with LibreOffice installed on the server, the WebUI can render previews of DOCX, PPTX, and XLSX files directly in the browser
Indexing and search — artifacts support indexing, so you can search and find any file that has been created or uploaded across your sessions.
Artifact URIs (artifact://...) are resolved by the entrypoint, so the frontend receives fully embedded content without extra HTTP round-trips. The maximum artifact size defaults to 10MB but is configurable.
6. Speech
The WebUI supports both Speech-to-Text (STT) and Text-to-Speech (TTS), turning it into a voice-enabled interface for your agents.
Speech-to-Text lets you dictate messages instead of typing. Supported providers:
-
Azure Cognitive Services — configurable language and region
-
OpenAI Whisper — high-quality transcription
Text-to-Speech reads agent responses aloud. Supported providers:
-
Google Gemini — 30+ voices (Kore, Puck, Zephyr, and more)
-
Azure Neural Voices — DragonHD and standard neural voices
-
AWS Polly — additional voice options
The frontend exposes settings for voice selection, playback rate, and caching. Markdown is automatically preprocessed to strip formatting before synthesis, so the agent’s response sounds natural when read aloud.
frontend_feature_enablement:
speechToText: true
textToSpeech: true
7. Background Tasks
Some agent operations take time — complex analysis, multi-step workflows, or tasks that involve calling multiple peer agents. The WebUI’s background task support lets these run without keeping your browser tab open.
When a task is submitted with background execution enabled:
-
The task continues running on the server even if you close the browser or lose connection
-
Events are persisted to the database for later replay
-
You can reconnect to a running background task and pick up the streaming response from where you left off
-
A status polling endpoint lets you check on progress without an SSE connection
-
Background tasks have a configurable timeout (default: 1 hour)
frontend_feature_enablement:
background_tasks: true # task_logging must also be enabled
background_tasks:
default_timeout_ms: 3600000 # 1 hour
This is useful for fire-and-forget workflows — kick off a lengthy report generation, go work on something else, and come back to the results later.
8. Sharing
The WebUI supports sharing conversations with other users through shareable links. This is useful for collaboration, review, or simply showing someone an interesting agent interaction.
Sharing features include:
-
Create share links for any session with configurable expiration and optional password protection
-
Role-based access — control who can view the shared session
-
Fork shared sessions — recipients can fork (copy) a shared conversation into their own workspace and continue it independently
-
Snapshot updates — update the shared snapshot as the conversation progresses
Sharing requires an identity service and SQL persistence to be configured.
9. End-to-End Stimulus Visualization
One of the more unique features of the WebUI is real-time message visualization. This lets you watch the actual messages flowing between agents in the mesh as they collaborate on your task.
You can monitor different scopes:
-
Your own messages — see the A2A messages generated from your interactions
-
Namespace messages — monitor all A2A traffic in a namespace
-
Specific agent messages — watch traffic to/from a particular agent
This is invaluable for understanding how agents collaborate, debugging multi-agent workflows, and getting a feel for the event-driven architecture underpinning Solace Agent Mesh. When you ask the orchestrator a question and it delegates to specialized agents, you can see exactly what’s happening under the hood.
Summary
The WebUI Entrypoint is the built-in, browser-based interface for interacting with your Solace Agent Mesh. It goes well beyond a simple chat window — with session management, projects, a prompt library, artifact handling, speech capabilities, background tasks, sharing, and real-time stimulus visualization, it provides a full workspace for working with AI agents.
Whether you’re a developer building and testing agents, a team collaborating on AI-driven workflows, or just exploring what Solace Agent Mesh can do, the WebUI Entrypoint is your starting point. And because every feature is configurable, you can start simple and scale up as your needs grow.
For more information about Solace Agent Mesh, visit the official Agent Mesh GitHub repository