一个用于可扩展的多智能体服务脚手架工程。

引言：把多智能体从“能跑”变成“可交付”

多智能体项目常常从一个对话 Demo 起步，却很快面对模型服务、流式协议、子 Agent、数据召回、配置管理、网关和在线验证等工程问题。每个项目从头解决这些问题，既慢也难以形成稳定标准。

Muye Multi-Agent 的初衷是提供一个完整但不过度封装的参考工程：开发者可以看到各服务如何分层、如何由 SDK 统一 Agent 协议、如何在本地体验流式交互，以及如何把业务代码替换进已有的安全和运行边界。它不是一键生成业务系统，而是一条可理解、可裁剪的标准化起跑线。

什么是 Muye Multi-Agent

Muye Multi-Agent 是基于 muye-multi-agent-sdk 的多服务脚手架。SDK 是嵌入每个 Agent 进程的 Python 库；Muye Multi-Agent 则把模型网关、主编排 Agent、两个示例子 Agent、可选数据召回服务与网关控制台组织成可运行工程。

组件	默认端口	责任
muye-llm	9850	OpenAI-compatible 模型、Embedding 与可选 Rerank 网关
muye-data	9840	可选只读 Dense/Keyword/Hybrid 检索服务
agent-main	9860	主对话、SSE、工具和子 Agent 编排
agent-travel	8011	ReAct 旅行参考 Agent，提供 public profile
agent-order	8012	Graph 订单流程参考 Agent，仅 internal profile
muye-gateway	80/443 或本地 9870	生产 Nginx 边界与本地运维控制台

Github仓储：https://github.com/muye-x/muye-multi-agent

适用场景

• 为企业内部知识问答、流程助手或行业助手搭建多 Agent 原型。
• 学习 Agent internal HTTP、SSE、取消、会话与 public/internal profile 的边界。
• 将已有模型供应商接入统一模型 alias、Embedding 与 Rerank 管理。
• 在不让 Agent 直接持有数据库凭据的前提下接入只读检索。
• 将 Travel 和 Order 示例替换为自己的领域 Agent，并由主 Agent 统一编排。

示例 Agent 不执行真实旅行预订、订单写入或数据库修改。生产业务必须自行增加认证、授权、审计、幂等、事务和领域风控。

技术架构

Client
  -> 可选 Nginx Gateway（TLS、Bearer Token、SSE 透传）
  -> agent-main（使用 SDK）
       -> muye-llm -> OpenAI-compatible 上游模型
       -> agent-travel / agent-order（使用 SDK internal 协议）
       -> 可选 muye-data -> Milvus 或 OpenSearch
                            -> muye-llm（Embedding / 可选 Rerank）

几个边界尤其重要：

• SDK 是库，不是一个独立中心服务。
• muye-data 只接受逻辑 resource alias，不暴露物理库表、数据库凭据或写入能力。
• 生产 Gateway 仅允许 /agentMain/ 与 /api/v1/travel/ 对公网开放；Order、LLM、Data 和 SDK internal 接口必须位于可信网络。
• 本地控制台仅监听 127.0.0.1:9870，它用于开发和运维体验，不等同于生产公网入口。

功能一览

• 模型中心：Chat、SSE、Embedding、模型 alias、thinking 参数校验和可选 Rerank。
• 主编排 Agent：对话接口、Block Stream V2 SSE、会话历史、工具路由与子 Agent 调用。
• Agent 示例：Travel 展示 ReAct + LangChain 工具；Order 展示 GraphAgent + LangGraph 状态图。
• 数据召回：Milvus/OpenSearch 适配，Dense、Keyword、Hybrid、RRF 融合和可选 Rerank。
• 网关与控制台：生产 Nginx 的 TLS/Bearer allowlist，以及本地在线体验页面。
• 运行治理：SDK 提供会话互斥、取消、超时、上下文和 internal/public 输出边界。

使用方法

1. 安装环境依赖

要求 Python 3.11 或更高。仓储使用根目录 .venv：

cd scaffold
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt

根 requirements.txt 会从 GitHub 的 v1.1.0 tag 安装 SDK，并包含各服务依赖。

2. 配置本地环境

从模板创建本地配置：

cp .env.example .env

至少配置模型网关所需项目：

MUYE_LLM_API_BASE_URL=https://your-openai-compatible-endpoint.example/v1
MUYE_LLM_API_KEY=
MUYE_LLM_DEFAULT_MODEL=your-model-alias
MUYE_LLM_MODELS_JSON=[{"id":"your-model-alias","name":"Your Model","provider_model":"provider-model","supports_thinking":false}]

MUYE_LLM_EMBED_API_BASE_URL=https://your-openai-compatible-endpoint.example/v1
MUYE_LLM_EMBED_API_KEY=
MUYE_LLM_EMBED_DEFAULT_MODEL=your-embedding-alias
MUYE_LLM_EMBED_MODELS_JSON=[{"id":"your-embedding-alias","name":"Your Embedding Model","provider_model":"provider-embedding-model","dimensions":1024}]

本地默认关闭数据服务：

MUYE_DATA_ENABLED=false

只有需要知识召回时才将其设为 true，并依据 muye-data/config.example.yaml 创建 config.yaml、配置资源和只读数据库连接。密钥、Token、数据库 URI 与本地 .env 均不得提交。

配置优先级为：

Shell 环境变量 > 根目录 .env > 服务目录 .env > 源码默认值

3. 启动与自检

先验证服务入口与配置结构：

.venv/bin/python main.py --dry-run

准备好模型配置后，启动全部本地服务：

.venv/bin/python main.py --timeout 20

启动器按 muye-llm -> muye-data（启用时） -> agent-main -> agent-travel -> agent-order -> dashboard-api 的顺序启动并等待健康检查。

4. 在线体验测试

打开本地控制台：

http://127.0.0.1:9870/console/online.html

控制台可选择主 Agent 或 Travel public profile，展示 SSE 文本、工具状态和思考事件。也可用命令行检查服务：

curl http://127.0.0.1:9860/health
curl http://127.0.0.1:8011/capabilities
curl -N -X POST http://127.0.0.1:9860/api/v1/chat/stream \
  -H 'Content-Type: application/json' \
  -d '{"user_input":"规划一次示例旅行","user_id":"demo","session_id":"demo-1"}'

注意：线上部署不要直接暴露这些端口。通过 Nginx Gateway 公开的请求需要 Bearer Token，且只应开放 allowlist 中的路由。

5. 自定义开发

推荐从最接近业务的一层开始替换：

1. 新增领域 Agent：复制 Travel 或 Order 的结构，选择 ReAct、Graph 或 Custom 模式，实现领域工具和 metadata。
2. 注册到主 Agent：在 agents/agent-main/tools/sub_agent/registry.py 添加可信内部地址，并在主 Agent 的工具路由中加入调用策略。
3. 接入数据召回：在业务 Agent 中使用 SDK DataClient；固定 resource、过滤条件和返回字段，禁止模型拼接数据库查询。
4. 替换模型配置：在 MUYE_LLM_MODELS_JSON 中维护业务可用 alias，而非让调用方传任意上游模型名。
5. 完善生产边界：将服务绑定到回环或私网，使用 Gateway TLS/Bearer Token，并为真实写操作增加鉴权、审计和幂等控制。

6. 单服务调试

需要独立调试时进入服务目录并使用同一个根 .venv：

cd muye-llm
cp .env.example .env
../.venv/bin/python main.py

cd ../agents/agent-travel
cp .env.example .env
../../.venv/bin/python main.py

每个服务 README 说明了更具体的配置与接口。独立入口不读取仓储根 .env，应在目标服务目录准备自己的 .env。

验证与交付前检查

PYTHONPATH=muye-llm:muye-gateway \
  .venv/bin/python -m pytest -q muye-llm/tests muye-gateway/dashboard_api/tests
PYTHONPATH=muye-data \
  .venv/bin/python -m pytest -q muye-data/tests
PYTHONPATH=agents/agent-main \
  .venv/bin/python -m pytest -q agents/agent-main/tests
PYTHONPATH=agents/agent-travel:agents/agent-order \
  .venv/bin/python -m pytest -q agents/agent-travel/tests agents/agent-order/tests
.venv/bin/python -m pytest -q tests
.venv/bin/python main.py --dry-run

生产 Gateway 还应执行 muye-gateway/scripts/smoke-test.sh，并在真实网络边界验证未授权请求被拒绝、SSE 不被缓冲、internal 服务不能从公网访问。

结语

SDK 解决的是 Agent 服务的通用运行时和协议问题；Muye Multi-Agent 展示的是这些能力如何组合成可体验、可扩展的系统。先以小范围、只读、可观测的 Agent 建立业务闭环，再逐步引入数据召回、更多子 Agent 和生产治理，通常比一次性构建“万能智能体”更可靠。

GitHub仓储

SDK的独立仓储：https://github.com/muye-x/muye-multi-agent-sdk
多Agent脚手架(基于SDK)：https://github.com/muye-x/muye-multi-agent