# https://github.com/SolaceLabs/solace-agent-mesh Project Manual

Generated at: 2026-06-24 20:55:28 UTC

## Table of Contents

- [Overview and System Architecture](#page-1)
- [Agents, A2A Protocol, and Built-in Tools](#page-2)
- [Gateways, Workflows, and Frontend (WebUI)](#page-3)
- [Deployment, Configuration, and Extensibility](#page-4)

<a id='page-1'></a>

## Overview and System Architecture

### Related Pages

Related topics: [Agents, A2A Protocol, and Built-in Tools](#page-2), [Gateways, Workflows, and Frontend (WebUI)](#page-3), [Deployment, Configuration, and Extensibility](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/README.md)
- [src/solace_agent_mesh/shared/api/pagination.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/shared/api/pagination.py)
- [src/solace_agent_mesh/shared/api/response_utils.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/shared/api/response_utils.py)
- [src/solace_agent_mesh/shared/api/__init__.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/shared/api/__init__.py)
- [src/solace_agent_mesh/services/platform/api/__init__.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/__init__.py)
- [src/solace_agent_mesh/services/platform/api/dependencies.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/dependencies.py)
- [src/solace_agent_mesh/services/platform/api/routers/__init__.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/routers/__init__.py)
- [src/solace_agent_mesh/services/platform/api/routers/dto/responses/__init__.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/routers/dto/responses/__init__.py)
- [client/webui/frontend/README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/README.md)
- [client/webui/frontend/src/lib/api/models/service.ts](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/src/lib/api/models/service.ts)
- [client/webui/frontend/src/lib/api/sessions/service.ts](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/src/lib/api/sessions/service.ts)
- [client/webui/frontend/src/lib/api/features/types.ts](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/src/lib/api/features/types.ts)
- [evaluation/README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/evaluation/README.md)
</details>

# Overview and System Architecture

## Purpose and Scope

Solace Agent Mesh (SAM) is a multi-protocol agent platform that allows developers to compose, deploy, and observe AI agents that exchange messages over a Solace message broker. The repository bundles four cooperating subsystems: a Python core that runs the agents, a Platform Service that exposes model and provider configuration, a React-based Web UI for human interaction, and an evaluation framework for regression testing.

The repository's [README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/README.md) documents a tutorial catalog that signals the breadth of integration points the platform targets — weather plugins, SQL database adapters, MCP servers, Slack bridges, and Microsoft Teams connectors (with Azure AD) — all of which are delivered as agents that participate in the same mesh.

The system is intentionally protocol-agnostic at the agent level. Community discussions (issues #1507 and #1582) describe the current A2A and MCP support and propose bridging protocols such as IACP for cross-protocol communication. The shared API layer and platform service infrastructure described below are the substrate that makes these protocol bridges possible.

## System Components

```mermaid
flowchart LR
    UI[React Web UI<br/>client/webui/frontend] -->|REST + SSE| API[Platform Service<br/>FastAPI]
    UI -->|REST + SSE| Core[Agent Core<br/>src/solace_agent_mesh]
    API --> DB[(SQLite / PostgreSQL)]
    Core -->|A2A / MCP| Broker((Solace Broker))
    Eval[Evaluation Framework<br/>evaluation/] --> Core
    Eval --> Broker
    Broker --> Agents[Plugin Agents<br/>Weather, SQL, MCP, Slack, Teams]
```

| Component | Path | Role |
|-----------|------|------|
| Agent Core | `src/solace_agent_mesh/` | Hosts agent components, shared utilities, and the A2A / MCP integration layer. |
| Platform Service | `src/solace_agent_mesh/services/platform/api/` | FastAPI application for model configuration, provider discovery, and health checks. |
| Web UI | `client/webui/frontend/` | React 19 + TypeScript SPA that streams events via SSE and calls the REST API. |
| Evaluation Framework | `evaluation/` | Runs end-to-end behavioral tests against a live broker via the `sam eval` CLI. |

The Platform Service exposes its routers under the `/api/v1/platform` prefix, with three community routers always mounted: health, models, and providers (Source: [src/solace_agent_mesh/services/platform/api/routers/__init__.py:18-38]()). Feature-flag-disabled endpoints return `501 Not Implemented` rather than being conditionally routed.

The Platform Service initializes its SQLAlchemy engine dialect-aware: SQLite is configured with `NullPool` and WAL mode for multi-threaded access, while PostgreSQL and MySQL use standard pooling with `pre_ping` (Source: [src/solace_agent_mesh/services/platform/api/dependencies.py:55-70]()). The component instance and session factory are stored in module-level globals so FastAPI dependencies can resolve them per request.

## Shared API Standards

All REST endpoints in the platform share a common envelope model implemented in `src/solace_agent_mesh/shared/api/`. Three primitives are exported from the package: `PaginationParams`, `PaginatedResponse`, and `DataResponse` (Source: [src/solace_agent_mesh/shared/api/__init__.py:8-25]()).

- `PaginationParams` enforces `page_number >= 1` and `1 <= page_size <= 100`, defaulting to page 1 of 20 items, and exposes an `offset` property for query construction (Source: [src/solace_agent_mesh/shared/api/pagination.py:21-32]()).
- `PaginatedResponse` builds the metadata block (`pageNumber`, `count`, `pageSize`, `nextPage`, `totalPages`) and computes `next_page` only when additional pages exist (Source: [src/solace_agent_mesh/shared/api/pagination.py:64-90]()).
- `DataResponse` is a thin generic wrapper used by single-record endpoints (Source: [src/solace_agent_mesh/shared/api/pagination.py:99-107]()).

`create_data_response` and `create_paginated_response` helpers in `response_utils.py` ensure the response shape remains `{ "data": ... }` and `{ "data": [...], "meta": { "pagination": {...} } }` across the surface (Source: [src/solace_agent_mesh/shared/api/response_utils.py:15-58]()).

The frontend consumes this exact envelope. The sessions service defines a `PaginatedSessionsResponse` type whose `meta.pagination` fields match the backend contract: `pageNumber`, `count`, `pageSize`, `nextPage`, `totalPages` (Source: [client/webui/frontend/src/lib/api/sessions/service.ts:5-15]()). The model configuration API similarly maps `ModelConfigurationListResponse` to the `data` / `total` shape (Source: [client/webui/frontend/src/lib/api/models/types.ts:21-24]()).

## Frontend Architecture

The Web UI is a React 19 application built with Vite, Tailwind CSS, and shadcn/ui primitives (Source: [client/webui/frontend/README.md:31-38]()). Communication with the backend uses two transports:

- **Server-Sent Events (SSE)** for streaming agent output, activity updates, and message progress.
- **REST** for configuration (model aliases, provider credentials) and session history (Source: [client/webui/frontend/README.md:13-21]()).

The frontend is modularized under `src/lib/`, with `api/`, `components/`, `hooks/`, `types/`, `contexts/`, `providers/`, and `utils/` as top-level folders. Model configuration requests carry either a `modelId` (for editing using stored credentials) or fresh `authConfig` / `modelParams` objects (for create flows), and the server merges both when present (Source: [client/webui/frontend/src/lib/api/models/service.ts:39-58]()).

Feature flags are surfaced through a typed `FeatureFlagInfo` contract that includes resolution phase, environment override status, and registry defaults, allowing the UI to render opt-in features predictably (Source: [client/webui/frontend/src/lib/api/features/types.ts:3-11]()).

## Cross-cutting Concerns

**Authentication.** The shared API package exposes `get_current_user` as the canonical FastAPI dependency for resolving the calling principal, ensuring every protected route uses the same identity extraction (Source: [src/solace_agent_mesh/shared/api/__init__.py:27-30]()). Release v1.28.2 introduced a fix to skip sentinel claim values when extracting user identifiers ([#1584](https://github.com/SolaceLabs/solace-agent-mesh/pull/1584)), which is the kind of edge case the centralized helper must guard against.

**Security hardening.** Recent releases have closed several issues: enabling optional TLS-verification skip for MCP servers ([#1495](https://github.com/SolaceLabs/solace-agent-mesh/pull/1495) in v1.24.1), bumping `mako` to 1.3.12 ([#1554](https://github.com/SolaceLabs/solace-agent-mesh/pull/1554) in v1.26.1), and addressing `gitpython` vulnerabilities ([#1527](https://github.com/SolaceLabs/solace-agent-mesh/pull/1527) in v1.25.1). The v1.28.3 release re-validates the SSRF guard and bumps Python dependencies plus OS packages ([#1587](https://github.com/SolaceLabs/solace-agent-mesh/pull/1587)). These advisories define the security posture users should expect.

**Evaluation.** The `evaluation/` directory ships a runnable harness invoked as `sam eval <suite.json>`, which is the supported way to validate agent behavior against a live Solace broker (Source: [evaluation/README.md:15-24]()). A convenience target `make test-eval-local` provisions a Python 3.12 venv and runs the local example suite, which is the recommended entry point for new contributors.

**Protocol bridges.** The architecture is designed to host heterogeneous agents: A2A agents and MCP servers already coexist, but issue #1507 flags the need for an explicit bridge (IACP) to translate between them. Issue #1582 demonstrates the bridge pattern in practice with the Nautilus A2A interop probe. New integrations should be designed as additional agents that attach to the mesh rather than as one-off protocol adapters.

## See Also

- [Pagination utilities reference](pagination.md) — detailed contract for `PaginationParams`, `PaginationMeta`, and `PaginatedResponse`.
- [Platform Service API](platform-service.md) — routers, DTOs, and dependency injection for the FastAPI app.
- [Web UI architecture](web-ui.md) — component layout, transport model, and feature flag integration.
- [Evaluation framework](evaluation.md) — running and authoring suites with the `sam eval` CLI.

---

<a id='page-2'></a>

## Agents, A2A Protocol, and Built-in Tools

### Related Pages

Related topics: [Overview and System Architecture](#page-1), [Gateways, Workflows, and Frontend (WebUI)](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/README.md)
- [src/solace_agent_mesh/agent/adk/app_llm_agent.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/agent/adk/app_llm_agent.py)
- [src/solace_agent_mesh/agent/sac/app.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/agent/sac/app.py)
- [src/solace_agent_mesh/agent/proxies/a2a/component.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/agent/proxies/a2a/component.py)
- [src/solace_agent_mesh/agent/proxies/base/component.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/agent/proxies/base/component.py)
- [src/solace_agent_mesh/agent/tools/registry.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/agent/tools/registry.py)
- [src/solace_agent_mesh/agent/tools/builtin_artifact_tools.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/agent/tools/builtin_artifact_tools.py)
- [src/solace_agent_mesh/agent/utils/artifact_helpers.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/agent/utils/artifact_helpers.py)
- [client/webui/frontend/README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/README.md)
- [client/sam-rest-client/src/sam_rest_client/client.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/sam-rest-client/src/sam_rest_client/client.py)
- [src/solace_agent_mesh/shared/api/pagination.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/shared/api/pagination.py)
</details>

# Agents, A2A Protocol, and Built-in Tools

## Overview

Solace Agent Mesh (SAM) is a framework for building AI applications composed of multiple specialized agents that collaborate over an event-driven mesh. Each agent is a Google ADK (Agent Development Kit) `LlmAgent` hosted inside a Solace AI Connector (SAC) app. Agents discover one another, exchange tasks over the Agent-to-Agent (A2A) protocol on Solace event brokers, and ship file artifacts using built-in tools.

The framework abstracts transport (Solace Platform), runtime (ADK), and discovery (A2A) so authors can focus on agent logic. Source: [README.md:1-12](README.md) describes SAM as "a flexible and configurable runtime environment built by integrating Google's Agent Development Kit (ADK) with the Solace AI Connector (SAC) framework."

## Agent Runtime Architecture

### ADK + SAC Integration

Each agent combines two layers:

- **SAC layer** — handles broker connections, YAML configuration loading, and component lifecycle. Source: [src/solace_agent_mesh/agent/sac/app.py](src/solace_agent_mesh/agent/sac/app.py) wires the agent into the SAC app lifecycle.
- **ADK layer** — provides the `LlmAgent` runtime, LLM interaction, tool execution, and state management. Source: [src/solace_agent_mesh/agent/adk/app_llm_agent.py](src/solace_agent_mesh/agent/adk/app_llm_agent.py) instantiates the ADK agent and binds configured tools and instructions.

Agent capabilities (model, instructions, tools, scopes) are declared primarily through SAC YAML configuration rather than hard-coded Python. Source: [README.md:9-16](README.md) confirms this design: "Define agent capabilities (LLM model, instructions, tools) primarily through SAC YAML configuration."

### Component Hierarchy

A2A communication is implemented as a proxy component layered on top of a base SAC component:

```mermaid
flowchart TD
    A[SAC App: app.py] --> B[Base Component<br/>proxies/base/component.py]
    B --> C[A2A Component<br/>proxies/a2a/component.py]
    A --> D[ADK LlmAgent<br/>adk/app_llm_agent.py]
    D --> E[Tool Registry<br/>tools/registry.py]
    E --> F[Built-in Artifact Tools<br/>tools/builtin_artifact_tools.py]
    F --> G[Artifact Helpers<br/>utils/artifact_helpers.py]
    C <-->|A2A over Solace| H[(Solace Event Broker)]
    I[Frontend Web UI] -->|REST + SSE| J[Platform Service]
    K[SAM REST Client] -->|invoke agent_name| J
    J --> H
```

Source: [src/solace_agent_mesh/agent/proxies/base/component.py](src/solace_agent_mesh/agent/proxies/base/component.py) supplies the shared broker and lifecycle primitives; [src/solace_agent_mesh/agent/proxies/a2a/component.py](src/solace_agent_mesh/agent/proxies/a2a/component.py) extends them with A2A-specific request/response handling and peer discovery.

## A2A Protocol and Inter-Agent Communication

### Standardized Communication Layer

SAM "creates a standardized communication layer where AI agents can: Delegate tasks to peer agents, Share data and artifacts, Connect with diverse user interfaces and external systems." Source: [README.md:39-46](README.md).

The A2A protocol rides on Solace Platform Event Brokers, providing:

- **Asynchronous, event-driven delivery** — decouples producers and consumers.
- **Dynamic peer discovery** — agents publish capability cards and learn about peers in the same ecosystem.
- **Task delegation** — agents invoke discovered peers through the A2A envelope over Solace. Source: [README.md:9-16](README.md) lists dynamic discovery and A2A delegation as core features.

### Client Integration

External callers and frontends talk to agents through gateways. The REST gateway exposes a `SAMRestClient.invoke` method:

```python
await client.invoke(
    agent_name="weather_agent",
    prompt="What is the forecast for Toronto?",
    files=[("context.csv", fh)],
    mode="async",          # or "sync"
    timeout_seconds=120,
)
```

Source: [client/sam-rest-client/src/sam_rest_client/client.py:42-55](client/sam-rest-client/src/sam_rest_client/client.py) shows the gateway invocation shape. Results expose typed artifact helpers for downloading produced content.

### Community Note: Interoperability

Because agents already speak A2A natively, bridging SAM to external A2A networks (for example, Nautilus A2A) is achievable without translation when those networks follow the same wire format. Source: community issue [#1582](https://github.com/SolaceLabs/solace-agent-mesh/issues/1582) discusses a live interoperability probe between SAM and Nautilus A2A. Conversely, issue [#1507](https://github.com/SolaceLabs/solace-agent-mesh/issues/1507) proposes an Inter-Agent Communication Protocol (IACP) to bridge agents that speak A2A and MCP, where translation at protocol boundaries becomes necessary.

## Built-in Tools

### Tool Registry

The `tools/registry.py` module is the entry point that the ADK agent uses to discover and bind available tools at startup. Source: [src/solace_agent_mesh/agent/tools/registry.py](src/solace_agent_mesh/agent/tools/registry.py) wires built-in tools (artifact management, SQL/JQ analysis, visualization, dynamic embeds) into the `LlmAgent`.

### Artifact Tools and Concurrency

Artifact operations are among the most heavily used built-in tools. Helper functions coordinate concurrent metadata loading using a module-level `asyncio.Semaphore(50)` named `_METADATA_LOAD_SEMAPHORE`. Both `get_artifact_info_list_fast` and `get_artifact_info_list` acquire this semaphore before touching artifact metadata. Source: [src/solace_agent_mesh/agent/utils/artifact_helpers.py:47-50](src/solace_agent_mesh/agent/utils/artifact_helpers.py) defines the semaphore.

> **Caveat:** Because `_METADATA_LOAD_SEMAPHORE` is module-level, sharing it across multiple event loops can cause `RuntimeError: ... attached to a different loop`. Source: community issue [#1591](https://github.com/SolaceLabs/solace-agent-mesh/issues/1591) documents this risk; deployments that spawn per-process loops should isolate artifact workloads accordingly.

The built-in artifact tools (`builtin_artifact_tools.py`) provide capabilities such as create, list, load, and metadata handling with automatic metadata injection. Source: [src/solace_agent_mesh/agent/tools/builtin_artifact_tools.py](src/solace_agent_mesh/agent/tools/builtin_artifact_tools.py) wraps these operations as ADK-callable tools.

## Integration Surfaces

| Surface | Mechanism | Source |
|---|---|---|
| Web UI (React 19 + Vite) | REST + Server-Sent Events for live agent flows | [client/webui/frontend/README.md:1-13](client/webui/frontend/README.md) |
| SAM REST Client (Python) | Async `invoke()` returning `SAMResult` with artifact helpers | [client/sam-rest-client/src/sam_rest_client/client.py](client/sam-rest-client/src/sam_rest_client/client.py) |
| Shared API utilities | PaginationParams, DataResponse, PaginatedResponse | [src/solace_agent_mesh/shared/api/pagination.py:13-17](src/solace_agent_mesh/shared/api/pagination.py) |

The shared API layer enforces consistent pagination defaults (`page_number=1`, `page_size=20`, max `100`) for REST endpoints. Source: [src/solace_agent_mesh/shared/api/pagination.py:11-13](src/solace_agent_mesh/shared/api/pagination.py).

## Common Failure Modes

- **Cross-loop semaphore reuse** — see [#1591](https://github.com/SolaceLabs/solace-agent-mesh/issues/1591); the artifact metadata semaphore is process-wide.
- **Peer discovery mismatch** — A2A agents must share naming/scope conventions to discover each other; misconfigured scopes silently prevent delegation.
- **REST gateway timeouts** — long-running multi-agent workflows can exceed the default `timeout_seconds=120`; raise the value for orchestrations that spawn sub-tasks.

## See Also

- [README.md](README.md) — project overview and quick start
- [client/webui/frontend/README.md](client/webui/frontend/README.md) — Web UI architecture
- [client/sam-rest-client/src/sam_rest_client/client.py](client/sam-rest-client/src/sam_rest_client/client.py) — REST client API
- [src/solace_agent_mesh/shared/api/pagination.py](src/solace_agent_mesh/shared/api/pagination.py) — shared API conventions
- Community: [IACP bridge proposal (#1507)](https://github.com/SolaceLabs/solace-agent-mesh/issues/1507), [Nautilus A2A bridge probe (#1582)](https://github.com/SolaceLabs/solace-agent-mesh/issues/1582), [semaphore loop issue (#1591)](https://github.com/SolaceLabs/solace-agent-mesh/issues/1591)

---

<a id='page-3'></a>

## Gateways, Workflows, and Frontend (WebUI)

### Related Pages

Related topics: [Overview and System Architecture](#page-1), [Agents, A2A Protocol, and Built-in Tools](#page-2), [Deployment, Configuration, and Extensibility](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/README.md)
- [client/webui/frontend/README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/README.md)
- [client/webui/frontend/package.json](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/package.json)
- [client/webui/frontend/src/lib/api/sessions/service.ts](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/src/lib/api/sessions/service.ts)
- [client/webui/frontend/src/lib/api/models/service.ts](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/src/lib/api/models/service.ts)
- [client/webui/frontend/src/lib/api/models/types.ts](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/src/lib/api/models/types.ts)
- [src/solace_agent_mesh/services/platform/api/__init__.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/__init__.py)
- [src/solace_agent_mesh/services/platform/api/dependencies.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/dependencies.py)
- [src/solace_agent_mesh/services/platform/api/routers/__init__.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/routers/__init__.py)
- [src/solace_agent_mesh/services/platform/api/routers/model_configurations_router.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/routers/model_configurations_router.py)
- [src/solace_agent_mesh/shared/api/__init__.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/shared/api/__init__.py)
- [src/solace_agent_mesh/shared/api/pagination.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/shared/api/pagination.py)
- [src/solace_agent_mesh/shared/api/response_utils.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/shared/api/response_utils.py)
</details>

# Gateways, Workflows, and Frontend (WebUI)

## Overview

Solace Agent Mesh (SAM) is a framework for composing multiple specialized AI agents that collaborate through the event-messaging layer of the Solace Platform. The project exposes its capabilities through three integration surfaces that this page documents:

- **Gateways** — interface adapters that bridge external protocols (REST, Slack, Teams, etc.) into the agent mesh.
- **Workflows** — multi-step orchestration of agents using the built-in Orchestrator component.
- **Frontend (WebUI)** — a React 19 single-page application that provides a chat interface, agent discovery, and artifact handling.

The frontend connects to the backend through standardized HTTP endpoints and live Server-Sent Events (SSE) streams. The Platform Service FastAPI application exposes community routers for health, model configuration, and providers, all prefixed under `/api/v1/platform`. Source: [README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/README.md).

> **Note on scope:** The retrieved source files in this page focus on the Frontend (WebUI) and the Platform Service API layer. Gateway and Workflow components are referenced at the project level (tutorials, Slack/Teams integrations) but their specific implementation files were not retrieved for this page. A separate gateway/workflow wiki page should cover those components in detail.

---

## Frontend (WebUI) Architecture

The WebUI is a React 19 + TypeScript SPA built with Vite, Tailwind CSS 4, and Radix UI primitives. It is organized into modular libraries under `src/lib/`:

| Module | Purpose |
|---|---|
| `/components` | Chat, UI, and page layout components |
| `/hooks` | Custom hooks for state and API integration |
| `/types` | TypeScript interfaces for frontend/backend contracts |
| `/contexts` | React contexts for global state |
| `/providers` | Provider components for dependency injection |
| `/utils` | Utility functions |

Source: [client/webui/frontend/README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/README.md).

### Key Components

- `ChatPage` — main chat interface with resizable panels and an artifact-preview sidepanel.
- `ChatMessageList` — styled message container.
- `ChatInputArea` — input component for sending messages to agents.
- `FlowChartPanel` — real-time visualization of agent communication flow.
- Activities Page (Enterprise only) — task/subtask list with flowcharts.

Source: [client/webui/frontend/README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/README.md).

### Transport Mechanisms

The frontend uses two transport mechanisms to talk to the backend:

- **Server-Sent Events (SSE)** — for live event streams from agents.
- **REST API** — for standard configuration and data operations (sessions, models, providers).

### Technology Stack

| Concern | Library |
|---|---|
| Framework | React 19, TypeScript |
| Build | Vite |
| Styling | Tailwind CSS 4, tailwind-merge, tailwind-scrollbar-hide |
| Components | Radix UI primitives, shadcn/ui |
| State/Data | TanStack React Query 5, React Hook Form + Zod |
| Routing | React Router 7 |
| PDF preview | react-pdf 9.2.1 |
| Resizable panels | react-resizable-panels 3 |
| Feature flags | @openfeature/* (core, react-sdk, web-sdk) |

Source: [client/webui/frontend/package.json](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/package.json).

### Development Setup

- Node.js version: `>=25.5.0` and `<26.0.0`.
- Install with `npm ci` inside `client/webui/frontend`.
- Run dev server: `npm run dev`. Lint with `npm run lint`.
- Pre-commit hook: run `git config core.hooksPath .hooks` from the repo root to enable automatic `npm run precommit` on commit.

Source: [client/webui/frontend/README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/README.md).

---

## API Layer and Integration Patterns

The Platform Service is a FastAPI application that exposes community endpoints under the `/api/v1/platform` prefix. The router registry always mounts all community routers; feature flags are checked inside endpoints, which return `501 Not Implemented` if disabled. Source: [src/solace_agent_mesh/services/platform/api/routers/__init__.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/routers/__init__.py).

```mermaid
flowchart LR
    WebUI["React WebUI<br/>(client/webui/frontend)"] -->|REST + SSE| FastAPI["Platform Service<br/>FastAPI app"]
    FastAPI --> Models["Model Configurations Router"]
    FastAPI --> Providers["Providers Router"]
    FastAPI --> Health["Health Router"]
    FastAPI --> Sessions["Sessions API<br/>/api/v1/sessions"]
    Models --> Service["ModelConfigService"]
    Service --> DB[("SQLAlchemy DB<br/>SQLite/Postgres/MySQL")]
```

### Standardized Response and Pagination

All API endpoints return a consistent shape: a single object as `{ "data": T }` or a list as `{ "data": [...], "meta": { "pagination": {...} } }`. Two helper modules enforce this:

- `PaginationParams` — request model with defaults `page_number=1`, `page_size=20`, `max_page_size=100`. Exposes an `offset` property for SQL queries.
- `PaginatedResponse.create()` — builds the response including `total_count`, `total_pages`, and `next_page` calculation.
- `DataResponse` — simple `{ data: T }` wrapper.
- Response helpers: `create_data_response`, `create_paginated_response`, `create_empty_data_response`, `create_success_response`, `create_list_response`.

Source: [src/solace_agent_mesh/shared/api/pagination.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/shared/api/pagination.py), [src/solace_agent_mesh/shared/api/response_utils.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/shared/api/response_utils.py).

### WebUI API Client Example: Sessions

The frontend's `sessions/service.ts` issues paginated requests and consumes the standard `meta.pagination` envelope. Example call for the recent-sessions query:

```ts
let url = `/api/v1/sessions?pageNumber=1&pageSize=${maxItems}`;
if (agentId) url += `&agent_id=${encodeURIComponent(agentId)}`;
const result = await api.webui.get<PaginatedSessionsResponse>(url);
return result.data || [];
```

The TypeScript response shape mirrors the backend's `PaginatedResponse`:

```ts
export interface PaginatedSessionsResponse {
    data: Session[];
    meta: { pagination: {
        pageNumber: number;
        count: number;
        pageSize: number;
        nextPage: number | null;
        totalPages: number;
    }};
}
```

Source: [client/webui/frontend/src/lib/api/sessions/service.ts](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/src/lib/api/sessions/service.ts).

### WebUI API Client Example: Model Configurations

The models service supports two credential-resolution modes for `fetchSupportedModelsByProvider`:

- **Editing mode** (`modelId` provided) — the server uses stored credentials from the database.
- **Creating mode** (no `modelId`) — credentials are passed in the request body, and the server merges them with any stored values when both are supplied.

This pattern lets the same endpoint serve both create and edit flows. Source: [client/webui/frontend/src/lib/api/models/service.ts](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/src/lib/api/models/service.ts).

### Platform Service Dependency Injection

The Platform Service uses module-level globals and FastAPI `Depends` to inject shared state:

- `set_component_instance(component)` — stores a reference to the `PlatformServiceComponent`; warns if already set.
- `init_database(database_url)` — configures SQLAlchemy with dialect-specific pooling: `NullPool` + WAL mode for SQLite, and pre-ping connection pooling for PostgreSQL/MySQL.
- The `get_platform_db`, `get_model_config_service`, and `get_component_instance` dependencies expose these to route handlers.

Source: [src/solace_agent_mesh/services/platform/api/dependencies.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/dependencies.py).

### Model Configurations Endpoint Behavior

The model configurations router reads/writes model aliases, providers, and auth through the `ModelConfigService`. It strips sensitive fields (API keys, OAuth secrets) from responses. After a successful update, the router emits a model-config update event on the topic returned by `get_model_config_update_topic(...)`, allowing dynamic provider subscribers to refresh. Source: [src/solace_agent_mesh/services/platform/api/routers/model_configurations_router.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/routers/model_configurations_router.py).

---

## Common Failure Modes and Community Notes

- **Workflow node agents hallucinating tool names** — addressed in v1.27.0 (commit `38d337c`, PR #1551). Workflow definitions should be tested with representative inputs to catch prompt-routing regressions.
- **Security advisories** — recent releases bumped `mako` (v1.26.1, PR #1554) and `gitpython` (v1.25.1, PR #1527) to clear vulnerabilities. MCP `skip_tls` verification was added in v1.24.1 (PR #1495) to support private/internal MCP servers.
- **Bridging protocols** — community issue #1507 proposes IACP as a bridge between A2A and MCP; #1582 explores a Solace Agent Mesh ↔ Nautilus A2A interoperability probe. These do not change current behavior but signal where gateway interoperability is heading.
- **Cross-event-loop semaphore** — issue #1591 notes a shared module-level `asyncio.Semaphore(50)` (`_METADATA_LOAD_SEMAPHORE` in `src/solace_agent_mesh/agent/utils/artifact_helpers.py`) that may be acquired across multiple event loops. When using gateways that spawn their own loops, monitor for `Semaphore` cross-loop warnings.

---

## See Also

- [README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/README.md) — top-level project overview, key features, quickstart, and tutorial index.
- [Solace Agent Mesh Documentation](https://solacelabs.github.io/solace-agent-mesh/) — full reference for gateways, orchestrator, plugins, and tutorials (Weather Agent, SQL Database, MCP, Slack, Microsoft Teams).
- [Releases](https://github.com/SolaceLabs/solace-agent-mesh/releases) — versioned changelog (current latest: v1.28.3).

---

<a id='page-4'></a>

## Deployment, Configuration, and Extensibility

### Related Pages

Related topics: [Overview and System Architecture](#page-1), [Agents, A2A Protocol, and Built-in Tools](#page-2), [Gateways, Workflows, and Frontend (WebUI)](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/README.md)
- [client/webui/frontend/README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/README.md)
- [client/webui/frontend/package.json](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/package.json)
- [client/webui/frontend/src/lib/api/models/service.ts](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/src/lib/api/models/service.ts)
- [client/webui/frontend/src/lib/api/models/types.ts](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/src/lib/api/models/types.ts)
- [client/webui/frontend/src/lib/api/features/types.ts](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/src/lib/api/features/types.ts)
- [evaluation/README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/evaluation/README.md)
- [src/solace_agent_mesh/services/platform/api/__init__.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/__init__.py)
- [src/solace_agent_mesh/services/platform/api/dependencies.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/dependencies.py)
- [src/solace_agent_mesh/services/platform/api/routers/__init__.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/services/platform/api/routers/__init__.py)
- [src/solace_agent_mesh/shared/api/pagination.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/shared/api/pagination.py)
- [src/solace_agent_mesh/shared/api/response_utils.py](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/src/solace_agent_mesh/shared/api/response_utils.py)
</details>

# Deployment, Configuration, and Extensibility

## Overview

Solace Agent Mesh (SAM) is a framework for orchestrating specialized AI agents over the Solace Platform Event Mesh. It exposes three broad surfaces that operators and integrators interact with:

- **Deployment** — packaging and running the platform service, the React Web UI, and the evaluation harness.
- **Configuration** — runtime database, broker, model, and feature-flag settings consumed by the FastAPI platform service.
- **Extensibility** — a plug-in model that adds new agents, protocols, providers, routers, and frontend modules without forking the core.

The framework is built on the Solace AI Connector (SAC), which gives it true event-driven scalability. Per the project README, SAM handles agent-to-agent delegation, artifact sharing, and multi-step workflows while letting integrators focus on agent skills rather than transport plumbing (Source: [README.md:13-25]()). Community discussions show growing interest in protocol bridging (e.g., IACP, A2A↔MCP, Nautilus interoperability), reinforcing that extensibility is a first-class concern (Source: [issue #1507](https://github.com/SolaceLabs/solace-agent-mesh/issues/1507), [issue #1582](https://github.com/SolaceLabs/solace-agent-mesh/issues/1582)).

## Platform Service Configuration

The Platform Service is a FastAPI application bootstrapped from `src/solace_agent_mesh/services/platform/api/`. Configuration is supplied at startup and then injected into request handlers via module-level singletons.

### Database initialization

`init_database` configures SQLAlchemy with dialect-aware pooling:

- **SQLite**: `NullPool` plus WAL mode for multi-threaded access.
- **PostgreSQL/MySQL**: standard connection pooling with `pre_ping` for stale connection recovery.

The session factory is stored in `PlatformSessionLocal`, and the live `PlatformServiceComponent` reference is kept in `platform_component_instance`. Both are write-once — repeated calls log a warning rather than overwriting (Source: [src/solace_agent_mesh/services/platform/api/dependencies.py:21-55]()).

### Router registration

Community routers are mounted under the `/api/v1/platform` prefix by the main application. The current community surface includes:

| Router | Tags | Purpose |
|--------|------|---------|
| `health_router` | Health | Liveness/readiness probes |
| `model_configurations_router` | Models | LLM model CRUD and validation |
| `providers_router` | Providers | Provider enumeration |

Feature flags gate behavior **inside** endpoints — disabled routes return `501 Not Implemented` rather than being omitted, which keeps the URL contract stable across deployments (Source: [src/solace_agent_mesh/services/platform/api/routers/__init__.py:23-50]()).

### Dependency injection

FastAPI `Depends` calls pull the active component and services from the module globals. This pattern avoids heavy context plumbing while still allowing tests to swap the component instance before app startup (Source: [src/solace_agent_mesh/services/platform/api/dependencies.py:30-38]()).

## API Standards and Extensibility

To keep frontends, SDKs, and third-party integrations compatible, SAM enforces a uniform API contract for paginated and single-record responses.

### Pagination

`PaginationParams` uses Pydantic aliases so HTTP query parameters (`pageNumber`, `pageSize`) map cleanly to Python fields. Defaults are `page_number=1`, `page_size=20`, capped at `MAX_PAGE_SIZE=100`. The `offset` property computes `(page_number - 1) * page_size` for SQL queries (Source: [src/solace_agent_mesh/shared/api/pagination.py:18-32]()).

### Standard response envelopes

`create_data_response` and `create_paginated_response` produce the two canonical shapes used everywhere:

- Single record: `{ "data": T }`
- List: `{ "data": [T], "meta": { "pagination": { ... } } }`

The shared helper `get_pagination_or_default` guarantees that any endpoint accepting an optional `PaginationParams` falls back to the documented defaults rather than `None` (Source: [src/solace_agent_mesh/shared/api/response_utils.py:8-55]()).

### Model configuration

The Models API is the primary extensibility surface for LLM backends. The frontend TypeScript mirrors the server schema in `ModelConfig`, capturing `alias`, `provider`, `modelName`, `apiBase`, `authType`, `authConfig`, `modelParams`, `maxInputTokens`, and audit fields. The companion `ModelConfigStatus` reports whether a model is configured (Source: [client/webui/frontend/src/lib/api/models/types.ts:5-30]()).

Two retrieval modes are exposed: stored credentials (editing mode) and inline request credentials (creation mode), with the server merging both when both are supplied (Source: [client/webui/frontend/src/lib/api/models/service.ts:38-60]()).

### Feature flags

Feature flags surface to the UI via `FeatureFlagInfo`, which exposes `key`, `release_phase`, `resolved`, `has_env_override`, `registry_default`, and `description`. This lets the UI gate panels (e.g., the Enterprise-only Activities page) without backend redeployment (Source: [client/webui/frontend/src/lib/api/features/types.ts:3-10]()).

## Frontend Deployment

The Web UI is a React 19 + Vite SPA with shadcn/ui primitives, Tailwind v4, and TanStack Query for server state. It requires **Node.js ≥ 25.5.0 and < 26.0.0** (Source: [client/webui/frontend/package.json:8-10]()). Install with `npm ci` and start the dev server via `npm run dev`; `npm run precommit` (or installing the repo-root hook via `git config core.hooksPath .hooks`) runs ESLint + Prettier (Source: [client/webui/frontend/README.md:24-60]()).

Communication with the backend is hybrid:

- **Server-Sent Events (SSE)** for live agent traffic and status.
- **REST** for configuration, listing, and CRUD endpoints.

## Evaluation Harness

The `evaluation/` directory ships a reproducible harness invoked through the `sam` CLI. Quick path: `make test-eval-local` (creates a Python 3.12 venv, installs the project plus `sam-rest-gateway`, runs the suite). The manual path is `pip install .` followed by `sam eval tests/evaluation/<suite>.json` (Source: [evaluation/README.md:7-30]()). The harness requires exported `SOLACE_BROKER_URL` and related broker environment variables before invocation.

## Failure Modes and Best Practices

- **Shared async primitives across event loops** — module-level `asyncio.Semaphore` instances must be bound to a single loop. The community has flagged `_METADATA_LOAD_SEMAPHORE` as a candidate for refactoring when running multi-loop test or worker configurations (Source: [issue #1591](https://github.com/SolaceLabs/solace-agent-mesh/issues/1591)).
- **Schema drift** — keep `ModelConfig` in `models/types.ts` in lockstep with the Pydantic response model; otherwise the edit/create merge logic silently drops fields.
- **Router mounting order** — community routers are always mounted; never rely on absence to gate a feature, always check the flag inside the handler.

## See Also

- Agent Development Tutorials (Weather, SQL, MCP, Slack) listed in [README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/README.md)
- Web UI component map in [client/webui/frontend/README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/client/webui/frontend/README.md)
- Evaluation suites under [evaluation/README.md](https://github.com/SolaceLabs/solace-agent-mesh/blob/main/evaluation/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: SolaceLabs/solace-agent-mesh

Summary: Found 10 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/SolaceLabs/solace-agent-mesh/issues/1507

## 2. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/SolaceLabs/solace-agent-mesh/issues/1593

## 3. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/SolaceLabs/solace-agent-mesh

## 4. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/SolaceLabs/solace-agent-mesh/issues/1591

## 5. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/SolaceLabs/solace-agent-mesh

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/SolaceLabs/solace-agent-mesh

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/SolaceLabs/solace-agent-mesh

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/SolaceLabs/solace-agent-mesh/issues/1582

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/SolaceLabs/solace-agent-mesh

## 10. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/SolaceLabs/solace-agent-mesh

<!-- canonical_name: SolaceLabs/solace-agent-mesh; human_manual_source: deepwiki_human_wiki -->