https://github.com/cognizant-ai-lab/neuro-san-studio
A playground for neuro-san
https://github.com/cognizant-ai-lab/neuro-san-studio
aaosa agentic-ai agentic-framework agents ai ai-agents ai-agents-framework langchain llms mas multi-agent multi-agent-framework multi-agent-systems nsflow sly-data
Last synced: 2 months ago
JSON representation
A playground for neuro-san
- Host: GitHub
- URL: https://github.com/cognizant-ai-lab/neuro-san-studio
- Owner: cognizant-ai-lab
- License: other
- Created: 2025-01-31T23:20:00.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-08-03T07:24:17.000Z (3 months ago)
- Last Synced: 2025-08-03T09:16:54.471Z (3 months ago)
- Topics: aaosa, agentic-ai, agentic-framework, agents, ai, ai-agents, ai-agents-framework, langchain, llms, mas, multi-agent, multi-agent-framework, multi-agent-systems, nsflow, sly-data
- Language: Python
- Homepage: https://decisionai.ml/neuro-san
- Size: 49.8 MB
- Stars: 185
- Watchers: 17
- Forks: 80
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Neuro San
Neuro SAN Studio
A playground for Neuro SAN - this repo includes working
examples to get started, explore, extend, and experiment with custom multi-agent networks!
---
Neuro SAN is the open-source library powering the Cognizant Neuro® AI Multi-Agent Accelerator, allowing domain experts,
researchers and developers to immediately start prototyping and building agent networks across any industry vertical.
---
Neuro SAN library
## What is Neuro SAN?
[**Neuro AI system of agent networks (Neuro SAN)**](https://github.com/cognizant-ai-lab/neuro-san) is an open-source,
data-driven multi-agent orchestration framework designed to simplify and accelerate the development of collaborative AI
systems. It allows users—from machine learning engineers to business domain experts—to quickly build sophisticated
multi-agent applications without extensive coding, using declarative configuration files (in HOCON format).
Neuro SAN enables multiple large language model (LLM)-powered agents to collaboratively solve complex tasks, dynamically
delegating subtasks through adaptive inter-agent communication protocols. This approach addresses the limitations inherent
to single-agent systems, where no single model has all the expertise or context necessary for multifaceted problems.
| Build a multi-agent network in minutes | Neuro SAN overview | Quick start |
|-------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| [](https://www.youtube.com/watch?v=wGxvPBN34Mk) | [](https://www.youtube.com/watch?v=NmniQWQT6vI) | [](https://youtu.be/gfem8ylphWA) |
---
### ✨ Key Features
* **🗂️ Data-Driven Configuration**: Entire agent networks are defined declaratively via simple HOCON files, empowering
technical and non-technical stakeholders to design agent interactions intuitively.
* **🔀 Adaptive Communication ([AAOSA Protocol](https://arxiv.org/abs/cs/9812015))**: Agents autonomously determine how
to delegate tasks, making interactions fluid and dynamic with decentralized decison making.
* **🔒 Sly-Data**: Sly Data facilitates safe handling and transfer of sensitive data between agents without exposing it
directly to any language models.
* **🧩 Dynamic Agent Network Designer**: Includes a meta-agent called the Agent Network Designer – essentially, an agent
that creates other agent networks. Provided as an example with Neuro SAN, it can take a high-level description of a
use-case as input and generate a new custom agent network for it.
* **🛠️ Flexible Tool Integration**: Integrate custom Python-based "coded tools," APIs, databases, and even external
agent ecosystems (Agentforce, Agentspace, CrewAI, MCP, A2A agents, LangChain tools and more) seamlessly into your agent workflows.
* **📈 Robust Traceability**: Detailed logging, tracing, and session-level metrics enhance transparency, debugging, and
operational monitoring.
* **🌐 Extensible and Cloud-Agnostic**: Compatible with a wide variety of LLM providers (OpenAI, Anthropic, Azure, Ollama,
etc.) and deployable in diverse environments (local machines, containers, or cloud infrastructures).
---
### Use Cases
Here are a few examples of use-cases that have been implemented with Neuro SAN.
For more examples, check out [docs/examples.md](docs/examples.md).
Agent Network
Use-Case
Description
🧬 Agent Network Designer
Automated generation of multi-agent HOCON configurations.
Generates complex multi-agent configurations from natural language input, simplifying the creation of intricate
agent workflows.
🛫 Airline Policy Assistance
Customer support for airline policies.
Agents interpret and explain airline policies, assisting customers with inquiries about baggage allowances, cancellations,
and travel-related concerns.
🏦 Banking Operations & Compliance
Automated financial operations and regulatory compliance.
Automates tasks such as transaction monitoring, fraud detection, and compliance reporting, ensuring adherence to
regulations and efficient routine operations.
🛍️ Consumer Packaged Goods (CPG)
Market analysis and product development in CPG.
Gathers and analyzes market trends, customer feedback, and sales data to support product development and strategic
marketing.
🛡️ Insurance Agents
Claims processing and risk assessment.
Automates claims evaluation, assesses risk factors, ensures policy compliance, and improves claim-handling efficiency
and customer satisfaction.
🏢 Intranet Agents
Internal knowledge management and employee support.
Provides employees with quick access to policies, HR, and IT support, enhancing internal communications and resource
accessibility.
🛒 Retail Operations & Customer Service
Enhancing retail customer experience and operational efficiency.
Handles customer inquiries, inventory management, and supports sales processes to optimize operations and service
quality.
📞 Telco Network Support
Technical support and network issue resolution.
Diagnoses network problems, guides troubleshooting, and escalates complex issues, reducing downtime and enhancing
customer service.
📞 Therapy Vignette Supervision
Generates treatment plan for a given therapy vignette.
A good example of using multiple different expert agents working together to come up with a single plan.
And many more: check out [docs/examples.md](docs/examples.md).
---
## High level Architecture
---
## Getting Started
To dive into Neuro SAN and start building your own multi-agent networks, this repository contains a collection of demos
for the [neuro-san library](https://github.com/cognizant-ai-lab/neuro-san).
You'll find comprehensive documentation, example agent networks, and tutorials to guide you through your first steps.
---
### Installation
Clone the repo:
```bash
git clone https://github.com/cognizant-ai-lab/neuro-san-studio
```
Go to dir:
```bash
cd neuro-san-studio
```
Ensure you have a supported version of python (e.g. 3.12 or 3.13):
```bash
python --version
```
Create a dedicated Python virtual environment:
```bash
python -m venv venv
```
Source it:
* For Windows:
```cmd
.\venv\Scripts\activate.bat && set PYTHONPATH=%CD%
```
* For Mac:
```bash
source venv/bin/activate && export PYTHONPATH=`pwd`
```
Install the requirements:
```bash
pip install -r requirements.txt
```
**IMPORTANT**: By default the server relies on OpenAI's `gpt-4o` model. Set the OpenAI API key, and add it to your shell
configuration so it's available in future sessions.
You can get your OpenAI API key from . After signing up, create a new API key in the
API keys section in your profile.
**NOTE**: Replace `XXX` with your actual OpenAI API key.
**NOTE**: This is OS dependent.
* For macOS and Linux:
```bash
export OPENAI_API_KEY="XXX" && echo 'export OPENAI_API_KEY="XXX"' >> ~/.zshrc
```
* For Windows:
* On Command Prompt:
```cmd
set OPENAI_API_KEY=XXX
```
* On PowerShell:
```powershell
$env:OPENAI_API_KEY="XXX"
```
Other providers such as Anthropic, AzureOpenAI, Ollama and more are supported too but will require proper setup.
Look at the `.env.example` file to set up environment variables for specific use-cases.
For testing the API keys, please refer to this [documentation](./docs/api_key.md)
---
### Run
There are multiple ways in which we can now use the neuro-san server with a client:
#### Option 1: Using [`nsflow`](https://github.com/cognizant-ai-lab/nsflow) as a developer-oriented web client
If you want to use neuro-san with a FastAPI-based developer-oriented client, follow these steps:
* Start the server and client with a single command, from project root:
```bash
python -m run
```
* As a default
* Frontend will be available at: `http://127.0.0.1:4173`
* The client and server logs will be saved to `logs/nsflow.log` and `logs/server.log` respectively.
* To see the various config options for this app, on terminal
```bash
python -m run --help
```
Screenshot:
---
#### Option 2: Using a basic web client interface
A [basic web client interface](https://github.com/cognizant-ai-lab/neuro-san-web-client) is installed by default.
It's a great, simple example of how to connect to a neuro-san server and interact with it.
Start the server and the client in one single command:
```bash
python -m run --use-flask-web-client
```
The client and server logs will show on the screen,
and will also be saved to `logs/server.log` and `logs/client.log` respectively.
As a default, on a web browser you can now navigate to to start using the application.
Notes:
1. Expand the `Configuration` tab at the bottom of the interface to connect to the neuro-san server host and port
2. Choose an Agent Network Name, e.g. "music_nerd", click Update
This Agent Network Name should match the list of agent networks that are activated in the `registries/manifest.hocon`
file.
3. Type your message in the chat box and press 'Send' to interact with the agent network.
4. Optional: open the `Agent Network Diagram` tab to visualize the interactions between the agents.
5. Optional: open the `Agent Communications` tab to see the messages exchanged between the agents.
---
#### Option 3: Command Line Interface
You can also use [neuro-san](https://github.com/cognizant-ai-lab/neuro-san)'s command line interface (CLI) to start and
interact with the server.
* Export the following environment variables:
```bash
# Point the server to the manifest file containing the agent network configurations
export AGENT_MANIFEST_FILE="./registries/manifest.hocon"
# Point the server to the directory containing the agent Python tools
export AGENT_TOOL_PATH="./coded_tools"
```
* For further instructions, refer to the client/server [setup](https://github.com/cognizant-ai-lab/neuro-san/blob/main/README.md#clientserver-setup)
in neuro-san.
---
## User guide
Ready to dive in? Check out the [user guide](docs/user_guide.md) for a detailed overview of the neuro-san library
and its features.
---
## Tutorial
For a detailed tutorial, refer to [docs/tutorial.md](docs/tutorial.md).
---
## Examples
For examples of agent networks, check out [docs/examples.md](docs/examples.md).
---
## Developer Guide
For the development guide, check out [docs/dev_guide.md](docs/dev_guide.md).
## Blog posts
* [Code versus Model in Multi-Agentic Systems](https://medium.com/@evolutionmlmail/code-versus-model-in-multi-agentic-systems-e33cf581e32b):
dives into how to design reliable multi-agent systems by dividing responsibilities between LLM reasoning
and coded tools.
* [Neuro SAN Is All You Need — A Data-Driven Multi-Agent Orchestration Framework](https://medium.com/@evolutionmlmail/neuro-san-is-all-you-need-a-data-driven-multi-agent-orchestration-framework-563fbd31a735):
explores Neuro SAN's architecture, configuration model, adaptive communication protocol (AAOSA),
and how it enables secure, extensible agent collaboration without hardcoded logic.
## More details
For more information, check out the [Cognizant AI Lab Neuro SAN landing page](https://decisionai.ml/neuro-san).