/ README.md
README.md
1 <p align="center"> 2 <img src="./docs/static/img/logo.png" alt="Solace Agent Mesh Logo" width="100"/> 3 </p> 4 <h2 align="center"> 5 Solace Agent Mesh 6 </h2> 7 <h3 align="center">Open-source framework for building event driven multi-agent AI systems</h3> 8 <h5 align="center">Star ⭐️ this repo to stay updated as we ship new features and improvements.</h5> 9 10 <p align="center"> 11 <a href="https://github.com/SolaceLabs/solace-agent-mesh/blob/main/LICENSE"> 12 <img src="https://img.shields.io/github/license/SolaceLabs/solace-agent-mesh" alt="License"> 13 </a> 14 <a href="https://pypi.org/project/solace-agent-mesh"> 15 <img src="https://img.shields.io/pypi/v/solace-agent-mesh.svg" alt="PyPI - Version"> 16 </a> 17 <a href="https://pypi.org/project/solace-agent-mesh"> 18 <img src="https://img.shields.io/pypi/pyversions/solace-agent-mesh.svg" alt="PyPI - Python Version"> 19 </a> 20 <a href="https://pypi.org/project/solace-agent-mesh"> 21 <img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/solace-agent-mesh?color=00C895"> 22 </a> 23 </p> 24 <p align="center"> 25 <a href="#-key-features">Key Features</a> • 26 <a href="#-quick-start-5-minutes">Quickstart</a> • 27 <a href="#️-next-steps">Next Steps</a> • 28 <a href="https://solacelabs.github.io/solace-agent-mesh/">Docs</a> 29 </p> 30 31 32 --- 33 34 **Solace Agent Mesh** is a framework that supports building AI applications where multiple specialized AI agents work together to solve complex problems. It uses the event messaging of [Solace Platform](https://solace.com) for true scalability and reliability. 35 36 With Solace Agent Mesh (SAM), you can create teams of AI agents, each having distinct skills and access to specific tools. For example, you could have a Database Agent that can make SQL queries to fetch data or a MultiModal Agent that can help create images, audio files and reports. 37 38 The framework handles the communication between agents automatically, so you can focus on building great AI experiences. 39 40 SAM creates a standardized communication layer where AI agents can: 41 * Delegate tasks to peer agents 42 * Share data and artifacts 43 * Connect with diverse user interfaces and external systems 44 * Execute multi-step workflows with minimal coupling 45 46 SAM is built on top of the Solace AI Connector (SAC) which allows Solace Platform Event Brokers to connect to AI models and services and Google's Agent Development Kit (ADK) for AI logic and tool integrations. 47 48 <p align="center"> 49 <img src="docs/static/img/Solace_AI_Framework_With_Broker.png" width="640" alt="SAM Architecture Diagram" /> 50 </p> 51 52 53 The result? A fully asynchronous, event-driven and decoupled AI agent architecture ready for production deployment. It is robust, reliable and easy to maintain. 54 55 56 --- 57 58 ## 🔑 Key Features 59 - **[Multi-Agent Event-Driven Architecture](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/getting-started/architecture)** – Agents communicate via the Solace Event Mesh for true scalability 60 - **[Agent Orchestration](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/components/agents)** – Complex tasks are automatically broken down and delegated by the [Orchestrator](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/components/orchestrator) agent 61 - **[Flexible Interfaces](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/components/gateways)** – Integrate with REST API, web UI, [Slack](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration), or build your own integration 62 - **[Extensible](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/components/plugins)** – Add your own agents, gateways, or services with minimal code 63 - **[Agent-to-Agent Communication](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/getting-started/architecture)** – Agents can discover and delegate tasks to each other seamlessly using the Agent2Agent (A2A) Protocol 64 - **[Dynamic Embeds](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/components/builtin-tools/embeds)** – Embed dynamic content like real-time data, calculations and file contents in responses 65 66 📚 **Want to know more?** Check out the full Solace Agent Mesh [documentation](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/getting-started/introduction/). 67 68 --- 69 70 ## 🚀 Quick Start (5 minutes) 71 72 Set up Solace Agent Mesh in just a few steps. 73 74 ### ⚙️ System Requirements 75 76 To run Solace Agent Mesh locally, you'll need: 77 78 - **Python 3.10.16 – 3.13.x** 79 - **pip** (comes with Python) 80 - **OS**: MacOS, Linux, or Windows (with [WSL](https://learn.microsoft.com/en-us/windows/wsl/)) 81 - **LLM API key** (any major provider or custom endpoint) 82 83 ### 🎸 Vibe Coding 84 To quickly setup and customize your Agent Mesh, check out the [Vibe Coding Quickstart Guide](docs/docs/documentation/vibe_coding.md). This guide walks you through the essential steps to get Solace Agent Mesh up and running with minimal effort. 85 86 ### 💻 Setup Steps 87 88 #### 1. Create a directory for a new project 89 ```bash 90 mkdir my-sam && cd my-sam 91 ``` 92 #### 2. Create and activate a Python virtual environment 93 ```bash 94 python3 -m venv .venv && source .venv/bin/activate 95 ``` 96 #### 3. Install Solace Agent Mesh (SAM) 97 Check if you have a version of SAM already installed. 98 ```bash 99 sam -v 100 ``` 101 If you have an earlier version, uninstall it and **start from scratch**: 102 ```bash 103 pip3 uninstall solace-agent-mesh 104 ``` 105 Note: Optionally, you can try to upgrade versions but this action is not officially supported at this time. (`pip3 install --upgrade solace-agent-mesh`) 106 107 If no previous version exists, install the latest version with: 108 ```bash 109 pip3 install solace-agent-mesh 110 ``` 111 #### 4. Initialize the new project via a GUI tool 112 ```bash 113 sam init --gui 114 ``` 115 Note: This initialization UI runs on port 5002 116 #### 5. Run the project 117 ```bash 118 sam run 119 ``` 120 #### 6. Verify SAM is running 121 Open the Web UI at [http://localhost:8000](http://localhost:8000) for the chat interface and ask a question 122 123 ### 🔧 Customize SAM 124 125 #### New agents can be added via a GUI interface 126 ```bash 127 sam add agent --gui 128 ``` 129 130 #### Existing plugins can be installed 131 ```bash 132 sam plugin add <your-component-name> --plugin <plugin-name> 133 ``` 134 135 --- 136 137 ## 🏗️ Architecture Overview 138 139 Solace Agent Mesh provides a "Universal A2A Agent Host," a flexible and configurable runtime environment built by integrating Google's Agent Development Kit (ADK) with the Solace AI Connector (SAC) framework. 140 141 The system allows you to: 142 143 - Host AI agents developed with Google ADK within the SAC framework 144 - Define agent capabilities (LLM model, instructions, tools) primarily through SAC YAML configuration 145 - Use Solace Platform as the transport for standard Agent-to-Agent (A2A) protocol communication 146 - Enable dynamic discovery of peer agents running within the same ecosystem 147 - Allow agents to delegate tasks to discovered peers via the A2A protocol over Solace 148 - Manage file artifacts using built-in tools with automatic metadata injection 149 - Perform data analysis using built-in SQL, JQ, and visualization tools 150 - Use dynamic embeds for context-dependent information resolution 151 152 ### Key Components 153 154 - **SAC** handles broker connections, configuration loading, and component lifecycle 155 - **ADK** provides the agent runtime, LLM interaction, tool execution, and state management 156 - **A2A Protocol** enables communication between clients and agents, and between peer agents 157 - **Dynamic Embeds** allow placeholders in responses that are resolved with context-dependent information 158 - **File Management** provides built-in tools for artifact creation, listing, loading, and metadata handling 159 160 --- 161 162 ## ➡️ Next Steps 163 164 Want to go further? Here are some hands-on tutorials to help you get started: 165 166 | 🔧 Integration | ⏱️ Est. Time | 📘 Tutorial | 167 |----------------|--------------|-------------| 168 | 🌤️ **Weather Agent**<br>Learn how to build an agent that gives Solace Agent Mesh the ability to access real-time weather information. | **~15 min** | [Weather Agent Plugin](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/developing/tutorials/custom-agent) | 169 | 🗃️ **SQL Database Integration**<br>Enable Solace Agent Mesh to answer company-specific questions using a sample coffee company database.| **~10–15 min** | [SQL Database Tutorial](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/developing/tutorials/sql-database) | 170 | 🧠 **MCP Integration**<br>Integrating a Model Context Protocol (MCP) Servers into Solace Agent Mesh. | **~10–15 min** | [MCP Integration Tutorial](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/developing/tutorials/mcp-integration) | 171 | 💬 **Slack Integration**<br>Chat with Solace Agent Mesh directly from Slack. | **~20–30 min** | [Slack Integration Tutorial](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/developing/tutorials/slack-integration) | 172 | 👔 **Microsoft Teams Integration (Enterprise)**<br>Connect Solace Agent Mesh Enterprise to Microsoft Teams with Azure AD authentication. | **~30–40 min** | [Teams Integration Tutorial](https://solacelabs.github.io/solace-agent-mesh/docs/documentation/developing/tutorials/teams-integration) | 173 174 --- 175 176 ## 👥 Contributors 177 178 Solace Agent Mesh is built with the help of our amazing community. Thanks to everyone who has contributed ideas, code and time to make this project better! 179 180 View the full list of contributors here: [GitHub Contributors](https://github.com/SolaceLabs/solace-agent-mesh/graphs/contributors) 💚 181 182 **Looking to contribute?** Check out [CONTRIBUTING.md](CONTRIBUTING.md) to get started and see how you can help! 183 184 --- 185 186 ## 📄 License 187 188 This project is licensed under the **Apache 2.0 License**. See the full license text in the [LICENSE](LICENSE) file. 189 190 --- 191 192 ## 🧪 Running Tests 193 194 This project uses `pytest` for testing. You can run tests using either `hatch` or `pytest` directly. 195 196 ### Using Hatch 197 198 The recommended way to run tests is through the `hatch` environment, which ensures all dependencies are managed correctly. 199 200 ```bash 201 # Run all tests 202 hatch test 203 204 # Run tests with tags 205 hatch test -m "<tag>" 206 ``` 207 208 ### Using Pytest Directly 209 210 If you prefer to use `pytest` directly, you must first install the project with its test dependencies. 211 212 ```bash 213 # Install the project in editable mode with the 'test' extras 214 pip install -e .[test] 215 216 # Run all tests 217 pytest 218 ``` 219 220 --- 221 222 <h3 align="center"> 223 <img src="./docs/static/img/solace-logo-text.svg" alt="Solace Agent Mesh Logo" width="100"/> 224 </h3>