使用说明

项目简介

PrimisAI Nexus 是一个强大的 Python 框架，旨在简化多智能体系统的构建和管理。它允许开发者创建复杂的智能体层级结构，并利用模型上下文协议 (MCP) 无缝集成外部工具服务，从而扩展大型语言模型 (LLM) 的功能。Nexus 专注于提供灵活、可扩展的架构，适用于需要多智能体协作和工具调用的复杂任务自动化场景。

主要功能点

多智能体管理: 支持创建和管理多个专业化智能体，并由中心协调器进行任务分配和监督。
层级监督结构: 允许构建主监督器和助理监督器，实现复杂的任务层级管理和委派。
MCP工具集成: 支持通过 MCP 协议自动发现和使用外部工具服务器，包括 SSE (HTTP) 和 stdio (本地子进程) 两种传输方式，方便集成各种本地或远程工具基础设施。
灵活的配置: 支持 YAML 配置文件，轻松定义和修改智能体层级结构，无需修改 Python 代码。
会话历史管理: 内置会话历史记录功能，支持 JSONL 格式存储，方便追踪和审计对话过程。
集成日志记录: 提供结构化的日志系统，方便在工作流目录中组织和查看日志信息，便于调试和问题排查。

安装步骤

安装 primisai 包: 使用 pip 从 PyPI 安装 Nexus：

pip install primisai

服务器配置

Nexus 本身作为一个智能体框架，其 MCP 服务器集成特性主要体现在能够 作为 MCP 客户端 与外部 MCP 服务器进行交互，从而利用外部工具。仓库中提供的 'examples/supervisor_multi_mcp' 和 'examples/agent_with_mcp_tools' 目录下包含了一些 MCP 服务器的示例代码 ('weather_server.py', 'add_server.py')，这些示例可以独立运行，作为工具服务器供 Nexus 智能体调用。

如果您需要使用 Nexus 框架连接到这些示例 MCP 服务器，或者您自己搭建的 MCP 服务器，您需要在 Nexus 智能体配置中指定 MCP 服务器的信息。 配置信息通常在创建 'Agent' 对象时通过 'mcp_servers' 参数传入，格式为 JSON 列表，每个元素描述一个 MCP 服务器连接：

SSE (HTTP) 服务器配置示例 (JSON):

[
  {
    "type": "sse",
    "url": "http://localhost:8000/sse",  // MCP 服务器 SSE 端点 URL，例如 examples/supervisor_multi_mcp/add_server.py 启动的服务器
    "auth_token": null  // (可选) 如果服务器需要身份验证，请提供令牌
  }
]

Stdio (本地子进程) 服务器配置示例 (JSON):

[
  {
    "type": "stdio",
    "script_path": "examples/supervisor_multi_mcp/weather_server.py" // MCP 服务器 Python 脚本路径，例如 examples/supervisor_multi_mcp/weather_server.py
  }
]

Nexus 客户端无需配置 MCP 服务器的启动命令，因为它作为 MCP 客户端，只需要知道如何连接到已经运行的 MCP 服务器。 MCP 服务器的启动和运行是独立于 Nexus 客户端的。您需要根据示例代码手动启动 'weather_server.py' 和 'add_server.py' 等 MCP 服务器，并确保 Nexus 客户端能够通过指定的 'url' 或 'script_path' 连接到这些服务器。

基本使用方法

创建智能体和监督器: 使用 'primisai.nexus.core.Agent' 和 'primisai.nexus.core.Supervisor' 类创建智能体和监督器实例。
注册智能体: 使用 'supervisor.register_agent()' 方法将智能体注册到监督器中，构建智能体层级结构。
配置 MCP 服务器: 在创建 'Agent' 实例时，通过 'mcp_servers' 参数配置要连接的 MCP 服务器列表。
启动交互会话: 调用 'supervisor.start_interactive_session()' 或 'agent.chat()' 方法开始与智能体系统进行交互。

示例代码 (参考 'examples/supervisor_multi_mcp/example_multi_mcp.py'):

import os, sys
from dotenv import load_dotenv

sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')))
from primisai.nexus.core import Agent, Supervisor

# ... (加载环境变量和 LLM 配置) ...

# MCP 服务器配置
weather_mcp = {
    "type": "stdio",
    "script_path": os.path.join(os.path.dirname(__file__), "weather_server.py") # 本地 stdio 服务器
}
add_mcp = {
    "type": "sse",
    "url": "http://localhost:8000/sse",  # 远程 SSE 服务器 (需预先启动 add_server.py 并监听 8000 端口)
}

# 创建使用 MCP 工具的智能体
weather_agent = Agent(
    name="WeatherAgent",
    llm_config=llm_config,
    system_message="You answer weather questions by using tools.",
    mcp_servers=[weather_mcp], # 配置 weather_mcp 服务器
    use_tools=True,
    keep_history=True
)

add_agent = Agent(
    name="AdditionAgent",
    llm_config=llm_config,
    system_message="You answer addition and math calculation queries.",
    mcp_servers=[add_mcp], # 配置 add_mcp 服务器
    use_tools=True,
    keep_history=True
)

# 创建监督器并注册智能体
supervisor = Supervisor(
    name="MultiMCP_Supervisor",
    llm_config=llm_config,
    system_message="You delegate math and weather queries to your agents."
)
supervisor.register_agent(weather_agent)
supervisor.register_agent(add_agent)

# 启动交互会话
supervisor.start_interactive_session()

注意: 要运行 'examples/supervisor_multi_mcp/example_multi_mcp.py' 示例，您需要：

启动 'examples/supervisor_multi_mcp/weather_server.py': 在一个终端窗口运行 'python examples/supervisor_multi_mcp/weather_server.py'，这将启动一个 stdio 类型的 MCP 天气服务器。
启动 'examples/supervisor_multi_mcp/add_server.py': 在另一个终端窗口运行 'python examples/supervisor_multi_mcp/add_server.py'，这将启动一个 SSE 类型的 MCP 加法服务器，监听 'http://localhost:8000/sse'。
运行 'examples/supervisor_multi_mcp/example_multi_mcp.py': 在第三个终端窗口运行 'python examples/supervisor_multi_mcp/example_multi_mcp.py'，这将启动 Nexus 客户端，连接到上述两个 MCP 服务器，并允许您与智能体进行交互，体验 MCP 工具集成功能。

关键词