Architecture Overview

Solace Agent Mesh is an event-driven framework that creates a distributed ecosystem of collaborative AI agents. The architecture decouples agent logic from communication and orchestration, enabling you to build scalable, resilient, and modular AI systems.

The framework integrates Solace Event Broker for messaging, Solace AI Connector (SAC) for component lifecycle management, and Google Agent Development Kit (ADK) for agent intelligence.

Architectural Principles

The design of Agent Mesh is founded on three key architectural principles:

Event-Driven Architecture

All interactions between major components are asynchronous and mediated by the Solace event broker, eliminating direct dependencies.

Component Decoupling

Gateways, Agent Hosts, and services communicate through standardized A2A protocol messages without knowing each other’s implementation.

Scalability & Resilience

Horizontal scaling of components with fault tolerance and guaranteed message delivery through the event broker.

Why Event-Driven?

The event-driven architecture provides several critical benefits:

Asynchronous Communication: Components don’t wait for responses, enabling high throughput
Loose Coupling: Services can be developed, deployed, and scaled independently
Fault Tolerance: The event broker ensures message delivery even if components fail
Dynamic Scaling: Add or remove components without system downtime
Complete Observability: All communication flows through the broker for monitoring

System Architecture Diagram

The following diagram illustrates how external systems, gateways, the event broker, agent hosts, and backend services interact:

Core Components

Solace Event Broker

The Solace Event Broker serves as the central nervous system of the agent mesh.

Overview
Topic Structure
Message Flow

The event broker provides:

Topic-based routing: Hierarchical topic structure for precise message routing
Request/reply patterns: Synchronous-style communication over async messaging
Publish/subscribe: For agent discovery and broadcast messages
Guaranteed delivery: Messages are persisted and delivered even if recipients are offline
High throughput: Handles millions of messages per second

Agent Mesh uses a hierarchical topic structure:

{namespace}/a2a/request/{agent_name}
{namespace}/a2a/response/{session_id}
{namespace}/a2a/status/{session_id}
{namespace}/a2a/discovery

Example topics:

solace_app/a2a/request/OrchestratorAgent
solace_app/a2a/response/session-abc123
solace_app/a2a/status/session-abc123
solace_app/a2a/discovery

Gateways

Gateways bridge external systems and the agent mesh, handling protocol translation and session management.

Gateways are SAC applications built using the Gateway Development Kit (GDK), which provides BaseGatewayApp and BaseGatewayComponent classes.

Key Responsibilities:

Protocol Translation

Convert external protocols (HTTP, WebSockets, Slack RTM) into standardized A2A protocol messages and vice versa.

Authentication & Authorization

Authenticate incoming requests and use a pluggable AuthorizationService to retrieve user permission scopes.

Session Management

Manage external user sessions and map them to A2A task lifecycles.

Response Handling

Handle asynchronous responses and status updates from agents, including streaming updates.

Embed Resolution

Perform late-stage processing like resolving artifact_content embeds before delivery to users.

Built-in Gateway Types:

app_module: solace_agent_mesh.gateway.http_sse.app

app_config:
  namespace: ${NAMESPACE}
  session_secret_key: "${SESSION_SECRET_KEY}"
  fastapi_host: ${FASTAPI_HOST, localhost}
  fastapi_port: ${FASTAPI_PORT, 8000}
  artifact_service: *default_artifact_service
  enable_embed_resolution: true

Agent Hosts and Agents

An Agent Host is a SAC application that hosts a single ADK-based agent.

Agent Host
Agent Definition
Agent Card

Agent Host Responsibilities:

Manages the lifecycle of the ADK Runner and LlmAgent
Handles A2A protocol translation between incoming requests and ADK Task objects
Enforces permission scopes by filtering available tools
Initializes ADK services (ArtifactService, MemoryService)
Publishes agent capabilities via AgentCard
Manages agent discovery and peer delegation

Configuration:

app_module: solace_agent_mesh.agent.sac.app

app_config:
  namespace: ${NAMESPACE}
  agent_name: "OrchestratorAgent"
  display_name: "Orchestrator"
  supports_streaming: true
  model: *planning_model
  instruction: |
    You are the Orchestrator Agent...

Agent Configuration Components:

Instructions

Define the agent’s persona, responsibilities, and behavior guidelines.

LLM Configuration

Specify model, API endpoint, temperature, max tokens, etc.

Toolset

Built-in tools, custom Python functions, or MCP Toolsets.

Services

Session service, artifact service, identity service configuration.

Example Agent Configuration:

agent_name: "OrchestratorAgent"
instruction: |
  You are the Orchestrator Agent. Process tasks,
  coordinate with peer agents, and manage workflows.

model:
  model: ${LLM_SERVICE_PLANNING_MODEL_NAME}
  api_base: ${LLM_SERVICE_ENDPOINT}
  api_key: ${LLM_SERVICE_API_KEY}
  temperature: 0.1
  max_tokens: 16000

tools:
  - tool_type: builtin-group
    group_name: "artifact_management"
  - tool_type: builtin-group
    group_name: "data_analysis"
  - tool_type: builtin
    tool_name: "get_current_time"

Agent Discovery via AgentCard:Each agent publishes an AgentCard describing its capabilities:

agent_card:
  description: "The Orchestrator manages tasks and coordinates multi-agent workflows."
  defaultInputModes: ["text"]
  defaultOutputModes: ["text", "file"]
  skills:
    - id: strategic_planning
      name: Strategic Planning
      description: Analyzes complex requests and creates structured execution plans.
    
    - id: agent_coordination
      name: Agent Coordination
      description: Coordinates multi-agent workflows and manages data handoffs.
    
    - id: artifact_management
      name: Artifact Management
      description: Creates, transforms, and manages various artifact types.

AgentCards are published to the discovery topic periodically:

agent_card_publishing:
  interval_seconds: 10

agent_discovery:
  enabled: true

The A2A Protocol

The Agent-to-Agent (A2A) protocol is the standardized communication protocol based on JSON-RPC 2.0.

Protocol Message Types

SendTaskRequest
StatusUpdate
SendTaskResponse
AgentCard

Purpose: Submit a task to an agentTopic: {namespace}/a2a/request/{agent_name}Structure:

{
  "jsonrpc": "2.0",
  "method": "a2a.sendMessage",
  "params": {
    "taskId": "task-abc123",
    "message": {
      "contextId": "session-xyz789",
      "parts": [
        {
          "kind": "text",
          "text": "What is the weather in London?"
        }
      ]
    }
  },
  "id": "req-1"
}

User Properties (Solace message headers):

{
  "a2a_client_id": "webui-gateway-001",
  "a2a_session_id": "session-xyz789",
  "a2a_reply_to_topic": "solace_app/a2a/response/session-xyz789",
  "a2a_user_id": "user-123"
}

Purpose: Stream progress updates during task executionTopic: {namespace}/a2a/status/{session_id}Structure:

{
  "jsonrpc": "2.0",
  "method": "a2a.updateStatus",
  "params": {
    "taskId": "task-abc123",
    "status": "working",
    "message": "Calling weather API...",
    "progress": 0.5
  }
}

Purpose: Deliver final task resultTopic: {namespace}/a2a/response/{session_id}Structure:

{
  "jsonrpc": "2.0",
  "result": {
    "taskId": "task-abc123",
    "message": {
      "contextId": "session-xyz789",
      "parts": [
        {
          "kind": "text",
          "text": "The current weather in London is partly cloudy with a temperature of 15°C."
        }
      ]
    }
  },
  "id": "req-1"
}

Purpose: Publish agent capabilities for discoveryTopic: {namespace}/a2a/discoveryStructure:

{
  "agentId": "OrchestratorAgent",
  "displayName": "Orchestrator",
  "description": "Manages tasks and coordinates workflows",
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text", "file"],
  "skills": [
    {
      "id": "strategic_planning",
      "name": "Strategic Planning",
      "description": "Creates structured execution plans"
    }
  ]
}

Message Parts

A2A messages contain an array of “parts” that can be different types:

{
  "kind": "text",
  "text": "Hello, how can I help you?"
}

Key Architectural Flows

User Task Processing Flow

This flow demonstrates how a user request moves through the system:

Request Initiation

User submits a request through a gateway (Web UI, Slack, REST API, etc.).

Authentication & Authorization

Gateway authenticates the request and retrieves user permission scopes via AuthorizationService.

A2A Task Creation

Gateway translates the request into an A2A task message, including scopes in message user properties.

Task Routing

Gateway publishes the message to the target agent’s request topic on the Solace Broker.

Agent Processing

Agent Host receives the message, extracts scopes, filters available tools, and initiates an ADK task.

LLM Interaction

ADK LlmAgent processes the task, invoking the LLM with filtered tools and generating a plan.

Tool Execution

Agent executes tools as needed, publishing status updates throughout the process.

Response Delivery

Agent publishes final response, gateway performs late-stage processing, and delivers result to user.

Agent-to-Agent Delegation Flow

Agents can delegate subtasks to peer agents while maintaining security context:

When agents delegate to peers, the original user’s permission scopes are propagated to maintain security context throughout the delegation chain.

Agent Discovery Flow

The system automatically discovers available agents through a publish-subscribe mechanism:

AgentCard Publishing

On startup and periodically, each Agent Host publishes an AgentCard describing its capabilities to the discovery topic.

Subscription

Gateways and other Agent Hosts subscribe to the discovery topic.

Registry Update

Upon receiving an AgentCard, components update their local AgentRegistry.

Agent Availability

Components are now aware of available agents for user selection (at gateways) or peer delegation (at agents).

Services and Storage

Agent Mesh provides pluggable services for various storage and management needs:

Session Service
Artifact Service
Identity Service

Purpose: Store conversation history and contextAvailable Types:

memory: In-memory storage (development only)
sql: SQLite, PostgreSQL, or other SQL databases
vertex_rag: Google Vertex AI RAG for vector-based retrieval

Configuration:

session_service:
  type: "sql"
  database_url: "${DATABASE_URL, sqlite:///session.db}"
  default_behavior: "PERSISTENT"

Behaviors:

PERSISTENT: Sessions persist across agent restarts
RUN_BASED: Sessions cleared when agent stops

Purpose: Store files and artifacts created by agentsAvailable Types:

memory: In-memory storage (development only)
filesystem: Local file system
gcs: Google Cloud Storage
s3: Amazon S3 or S3-compatible storage

Configuration:

artifact_service:
  type: "filesystem"
  base_path: "/tmp/samv2"
  artifact_scope: "namespace"

Scopes:

namespace: Artifacts shared across namespace
app: Artifacts isolated per application
custom: Custom scoping logic

Purpose: Retrieve user information and attributesAvailable Types:

local_file: JSON file with user data
Custom implementations via plugins

Configuration:

identity_service:
  type: local_file
  file_path: ./people/employees.json
  cache_ttl_seconds: 300

Advanced Features

Dynamic Embeds

Embeds allow late-stage resolution of placeholders in agent responses:

{{status_update}}Analyzing data...{{/status_update}}

Gateways resolve these embeds before delivering to users:

status_update: Rendered as streaming status message
artifact_content: File content loaded and embedded
calc: Mathematical expression evaluated

Artifact Handling Modes

ignore
embed
reference

Artifacts are not included in responses. Useful when artifacts are large or not needed by the client.

Auto-Summarization

Conversation history can be automatically summarized to manage context length:

auto_summarization:
  enabled: true
  compaction_percentage: 0.25  # Summarize 25% of history when triggered

Tool Permission Scopes

Tools can be restricted based on user permissions:

# Before model callback filters tools based on scopes
if "admin" not in user_scopes:
    filtered_tools = [t for t in tools if not t.requires_admin]

Deployment Architecture

Agent Mesh supports various deployment patterns:

Development (Single Process)
Distributed (Multiple Processes)
Containerized (Docker/Kubernetes)

All components run in a single process:

sam run

Simple setup
Easy debugging
Not suitable for production

Each component runs as a separate process:

# Terminal 1: Run orchestrator
sam run .solace/agents/orchestrator.yaml

# Terminal 2: Run weather agent
sam run .solace/agents/weather_agent.yaml

# Terminal 3: Run web UI
sam run .solace/gateways/webui_gateway.yaml

Better isolation
Independent scaling
Easier debugging of specific components

Each component runs in a container:

# docker-compose.yml
services:
  orchestrator:
    image: my-sam:latest
    command: run .solace/agents/orchestrator.yaml
  
  weather-agent:
    image: my-sam:latest
    command: run .solace/agents/weather_agent.yaml
  
  webui:
    image: my-sam:latest
    command: run .solace/gateways/webui_gateway.yaml
    ports:
      - "8000:8000"

Production-ready
Easy scaling
Infrastructure as code

Performance Considerations

Message Size

Keep A2A messages under 10MB (Solace broker limit). Use artifact references for large files.

Tool Parallelization

Enable parallel tool calls in LLM configuration:

model:
  parallel_tool_calls: true

Caching

Use prompt caching to reduce LLM costs:

model:
  cache_strategy: "5m"  # 5 minute cache

Batching

Configure stream batching threshold:

stream_batching_threshold_bytes: 120

Security Architecture

Gateway Authentication

Gateways authenticate users and retrieve permission scopes.

Scope Propagation

User scopes are included in A2A message user properties.

Tool Filtering

Agent Hosts filter available tools based on propagated scopes.

Delegation Context

When agents delegate to peers, scopes are propagated through the delegation chain.

Next Steps

Now that you understand the architecture:

Create Custom Agents

Learn how to build specialized agents for your use cases.

Build Gateways

Create custom gateways to integrate with your systems.

Deploy to Production

Learn best practices for production deployments.

Monitor & Debug

Set up observability and troubleshooting for your agent mesh.

Getting Started

Installation & Configuration

Core Concepts

Components

Built-in Tools

Developer Guides

Deployment

Enterprise Features

​Architecture Overview

​Architectural Principles

Event-Driven Architecture

Component Decoupling

Scalability & Resilience

​Why Event-Driven?

​System Architecture Diagram

​Core Components

​Solace Event Broker

​Gateways

​Agent Hosts and Agents

Instructions

LLM Configuration

Toolset

Services

​The A2A Protocol

​Protocol Message Types

​Message Parts

​Key Architectural Flows

​User Task Processing Flow

​Agent-to-Agent Delegation Flow

​Agent Discovery Flow

​Services and Storage

​Advanced Features

​Dynamic Embeds

​Artifact Handling Modes

​Auto-Summarization

​Tool Permission Scopes

​Deployment Architecture

​Performance Considerations

Message Size

Tool Parallelization

Caching

Batching

​Security Architecture

​Next Steps

Create Custom Agents

Build Gateways

Deploy to Production

Monitor & Debug

Build docs developers (and LLMs) love

Architecture Overview

Architectural Principles

Why Event-Driven?

System Architecture Diagram

Core Components

Solace Event Broker

Gateways

Agent Hosts and Agents

The A2A Protocol

Protocol Message Types

Message Parts

Key Architectural Flows

User Task Processing Flow

Agent-to-Agent Delegation Flow

Agent Discovery Flow

Services and Storage

Advanced Features

Dynamic Embeds

Artifact Handling Modes

Auto-Summarization

Tool Permission Scopes

Deployment Architecture

Performance Considerations

Security Architecture

Next Steps