Related Pages

Related topics: Agents, A2A Protocol, and Built-in Tools, Gateways, Workflows, and Frontend (WebUI), Deployment, Configuration, and Extensibility

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 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

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]

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), 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 in v1.24.1), bumping mako to 1.3.12 (#1554 in v1.26.1), and addressing gitpython vulnerabilities (#1527 in v1.25.1). The v1.28.3 release re-validates the SSRF guard and bumps Python dependencies plus OS packages (#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 — detailed contract for PaginationParams, PaginationMeta, and PaginatedResponse.
• Platform Service API — routers, DTOs, and dependency injection for the FastAPI app.
• Web UI architecture — component layout, transport model, and feature flag integration.
• Evaluation framework — running and authoring suites with the sam eval CLI.

Related Pages

Related topics: Overview and System Architecture, Gateways, Workflows, and Frontend (WebUI)

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 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 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 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 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:

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 supplies the shared broker and lifecycle primitives; 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.

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 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:

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 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 discusses a live interoperability probe between SAM and Nautilus A2A. Conversely, issue #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 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 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 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 wraps these operations as ADK-callable tools.

Integration Surfaces

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.

Common Failure Modes

• Cross-loop semaphore reuse — see #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 — project overview and quick start
• client/webui/frontend/README.md — Web UI architecture
• client/sam-rest-client/src/sam_rest_client/client.py — REST client API
• src/solace_agent_mesh/shared/api/pagination.py — shared API conventions
• Community: IACP bridge proposal (#1507), Nautilus A2A bridge probe (#1582), semaphore loop issue (#1591)

Related Pages

Related topics: Overview and System Architecture, Agents, A2A Protocol, and Built-in Tools, Deployment, Configuration, and Extensibility

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.

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.

Related Pages

Related topics: Overview and System Architecture, Agents, A2A Protocol, and Built-in Tools, Gateways, Workflows, and Frontend (WebUI)

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, issue #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:

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).
• 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
• Web UI component map in client/webui/frontend/README.md
• Evaluation suites under evaluation/README.md

Doramagic Pitfall Log

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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/SolaceLabs/solace-agent-mesh/issues/1507

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/SolaceLabs/solace-agent-mesh/issues/1593

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/SolaceLabs/solace-agent-mesh

4. Runtime risk: Runtime risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/SolaceLabs/solace-agent-mesh/issues/1591

5. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/SolaceLabs/solace-agent-mesh

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• 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
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/SolaceLabs/solace-agent-mesh

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/SolaceLabs/solace-agent-mesh/issues/1582

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/SolaceLabs/solace-agent-mesh

10. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/SolaceLabs/solace-agent-mesh

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using solace-agent-mesh with real data or production workflows.

• Blocking socket.getaddrinfo in async webhook path causes event loop star - github / github_issue
• Shared module-level _METADATA_LOAD_SEMAPHORE may be used across multiple - github / github_issue
• Proposal: IACP as a bridge protocol for A2A + MCP agent meshes - github / github_issue
• Bridging Solace Agent Mesh ↔ Nautilus A2A — interoperability probe + 10 - github / github_issue
• v1.28.3 - github / github_release
• v1.28.2 - github / github_release
• v1.28.1 - github / github_release
• v1.28.0 - github / github_release
• v1.27.1 - github / github_release
• v1.27.0 - github / github_release
• v1.26.1 - github / github_release
• v1.26.0 - github / github_release