Neuro SAN Studio核心揭秘：用HOCON声明式配置定义智能体网络（附Hello World模板）

Neuro SAN Studio是一个面向多智能体（Multi-Agent）系统的开源"游乐场"项目，它的核心思路是：用HOCON 声明式配置文件直接定义智能体网络——写清楚每个智能体的角色、指令和可协作的下游智能体，就能在几分钟内搭建并运行一个多智能体协作应用，无需编写复杂的编排代码。本文将拆解这套配置机制，并附赠一个可直接上手的Hello World 智能体网络模板🧩

一、快速认识：Neuro SAN Studio 多智能体编排入门

传统的单智能体系统往往受限于单一模型的知识边界，而Neuro SAN Studio（基于开源库 Neuro SAN）让多个大语言模型（LLM）驱动的智能体自适应地分工协作：

• 🗂️数据驱动配置：整个智能体网络用一个简单的 HOCON 文件声明式定义，技术人员和非技术人员都能看懂、能改
• 🔀AAOSA 自适应通信协议：智能体自主决定如何委派子任务，交互动态而灵活
• 🧩灵活工具集成：可挂载自定义 Python 工具、API、数据库，甚至其他智能体生态（MCP、A2A 等）
• 🌐云无关：兼容 OpenAI、Anthropic、Gemini、Ollama 等多种 LLM 提供方

💡HOCON（Human-Optimized Config Object Notation）是一种类 JSON 的配置格式，支持注释、include引用和变量替换，比纯 JSON 更适合人类协作维护。

整个项目的知识入口在 README.md，系统级用户文档在 docs/user_guide.md。

二、核心揭秘：HOCON 声明式配置如何定义智能体网络

理解 Neuro SAN Studio 只需抓住三件事：智能体字段、Front Man 规则、manifest 注册。

2.1 智能体字段速查表：name、function、instructions、tools

每个智能体在 HOCON 文件中由一组字段声明，核心字段如下（摘自 docs/user_guide.md）：

2.2 Front Man 智能体：谁才是对外的"唯一入口"

智能体网络必须有一个Front Man（前台智能体）——它负责与外部用户对话，并把任务委派给下游智能体。判定规则非常直观：

function中不定义任何parameters的智能体，就是 Front Man。它可以出现在tools列表的任何位置，网络内部可以是图结构，甚至允许环。

这一机制来自 registries/basic/hello_world.hocon 中的官方注释说明。

2.3 manifest.hocon：智能体网络的注册总开关

服务器启动时，会先读取 manifest 文件决定加载哪些智能体网络。在 registries/manifest.hocon 中可以看到典型写法——键是配置文件名，布尔值控制是否加载：

"basic/music_nerd.hocon": true, # 加载该智能体网络 "agent_network_architect.hocon": false # 暂不加载

它还会include各分组（basic、tools、industry 等）的子 manifest，实现分组注册、集中管理。

▲ 智能体网络整体架构：用户请求进入 Front Man 智能体，再经 AAOSA 协议流转给多个 Specialist 智能体，敏感数据可通过 Sly Data 安全传递而不暴露给 LLM。

三、附赠模板：Hello World 智能体网络逐段解析

这是官方提供的最小多智能体示例，完整文件见 registries/basic/hello_world.hocon，配套说明在 docs/examples/basic/hello_world.md。

3.1 文件结构总览

整个网络只有两个智能体，结构如下：

hello_world 智能体网络 ├── metadata 描述、标签、示例查询 ├── announcer Front Man：撰写简短公告，调用 synonymizer └── synonymizer 终端工具：为每个词找"5 个字母"的同义词

3.2 逐段拆解

① 引入共享 LLM 配置（L21-L25）：

include "config/llm_config.hocon"

通过include一次性复用全项目的 config/llm_config.hocon，换模型只需改一个文件，无需逐个智能体网络修改。

② metadata 元信息（L27-L33）：包含网络描述、标签和sample_queries（示例查询），方便 UI 展示和测试。

③ announcer —— Front Man（L47-L75）：

• function中只有description、没有parameters，因此它是 Front Man
• instructions要求它弄清"目标受众 + 情绪"，写出尽可能短的公告，并且必须调用 synonymizer
• tools = ["synonymizer"]声明了它唯一可调用的下游智能体

④ synonymizer —— 终端工具智能体（L79-L108）：

• function.parameters定义了入参：name（输入简述）和input_string（待处理文本）
• instructions要求它为每个词找一个恰好 5 个字母的同义词——这个约束正是引导输出趋向 "hello world" 的"暗门"

3.3 示例对话

按官方文档，输入这句提示词：

"From earth, I approach a new planet and wish to send a short 2-word greeting to the new orb."

理想结果是两个智能体协作输出：

Hello, world!

⚠️ 由于底层是 LLM，输出具有统计性，不保证 100% 复现——这正是多智能体世界的新常态 😉

四、上手实操：用 ns 命令一键启动智能体网络

4.1 安装与初始化项目

推荐用 uv 快速安装：

mkdir my_project && cd my_project uv init && uv venv && source .venv/bin/activate uv add neuro-san-studio

也可以 clone 源码获得全部能力：git clone https://gitcode.com/gh_mirrors/ne/neuro-san-studio

然后运行ns init初始化项目（ns即 Neuro SAN 的命令行别名），它会交互式选择 LLM 提供方，并自动创建config、registries、coded_tools、middleware等目录结构。

4.2 配置密钥、校验与启动服务器

export OPENAI_API_KEY="XXX" # 1) 设置 LLM API Key ns check-llm-keys # 2) 校验密钥是否可用 ns import hello_world # 3) 导入 Hello World 智能体网络 ns validate registries/basic/hello_world.hocon # 4) 结构校验（不调用 LLM，无需密钥） ns run # 5) 启动服务器 + nsflow 可视化界面

ns run启动后，Neuro SAN 服务器监听localhost:8080，nsflow 界面在http://localhost:4173/，日志统一落在logs/目录。

4.3 nsflow 界面：可视化你的智能体网络

▲ nsflow 界面一览：左侧是 manifest 注册的全部智能体网络，点击任意网络即可在中央查看其拓扑结构，并在右侧直接与 Front Man 对话。

此外，项目自带Agent Network Designer——一个"设计智能体网络的智能体"。在 nsflow 中点击NEW按钮，输入一句自然语言需求，它会自动创建智能体、建立连接、撰写指令并保存到registries/generated/，详见 docs/examples/agent_network_designer.md。

五、进阶指南：从 Hello World 走向真实业务

• ✅先校验再运行：ns validate会检查"引用了但没定义的智能体、Front Man 缺失、无效工具名"等结构性错误，完整参数见 docs/cli/validate.md
• ☕进阶示例：registries/basic/coffee_finder_advanced.hocon 演示了 HOCON 非 JSON 语法的变量替换（如${aaosa_call}{...}、${this_is_not_a_game}），以及 Front Man 如何调度CoffeeShop、Time、UserPreferences等下游智能体

▲ 真实的"找咖啡店"多智能体网络：一个 Front Man 智能体即可编排多个门店智能体与外部 API 工具。

• 📚更多资源：
  • 官方教程：docs/tutorial.md
  • 全部示例索引：docs/examples.md
  • LLM 配置详解（OpenAI / Anthropic / Gemini / Ollama 等）：docs/user_guide.md
  • 行业级案例（银行、保险、电信等 20+ 个智能体网络）：registries/industry/

写在最后

"配置即网络"是 Neuro SAN Studio 最有价值的设计：一个 HOCON 文件同时描述了谁负责什么、谁能调用谁、用哪个大模型，声明式地勾勒出整个多智能体系统。从 Hello World 的announcer → synonymizer双智能体链路开始，你只需复制模板、修改instructions、在 manifest 中注册，就能一步步搭建属于自己的智能体网络 🚀