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

---

✨ 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): 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.

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.

---

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.

You'll find comprehensive documentation, example agent networks, and tutorials to guide you through your first steps.

---

Installation

Clone the repo:

git clone https://github.com/cognizant-ai-lab/neuro-san-studio

Go to dir:

cd neuro-san-studio

Ensure you have a supported version of python (3.12 at this time):

python --version

Create a dedicated Python virtual environment:

python -m venv venv

Source it:

• For Windows:

  .\venv\Scripts\activate.bat && set PYTHONPATH=%CD%

• For Mac:

  source venv/bin/activate && export PYTHONPATH=`pwd`

Install the requirements:

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 https://platform.openai.com/signup. 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:

  export OPENAI_API_KEY="XXX" && echo 'export OPENAI_API_KEY="XXX"' >> ~/.zshrc

• For Windows:

  • On Command Prompt:

  set OPENAI_API_KEY=XXX

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

---

Run

There are multiple ways in which we can now use the neuro-san server with a client:

Option 1: Using 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:

  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

  python -m run --help

Screenshot:

---

Option 2: Using a basic web client interface

A basic web client interface 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:

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 http://127.0.0.1:5003/ 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's command line interface (CLI) to start and interact with the server.

• Export the following environment variables:

  # 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 in neuro-san.

---

User guide

Ready to dive in? Check out the user guide for a detailed overview of the neuro-san library and its features.

---

Tutorial

For a detailed tutorial, refer to docs/tutorial.md.

---

Examples

For examples of agent networks, check out docs/examples.md.

---

Developer Guide

For the development guide, check out docs/dev_guide.md.

Blog posts

• Code versus Model in Multi-Agentic Systems: 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: 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.