顺序思维多智能体系统 (MAS) English | 简体中文 该项目使用Agno框架构建并通过MCP提供服务的**多智能体系统（MAS）**实现了一个先进的顺序思维过程。它通过利用协调的、专门化的智能体进行更深入的分析和问题分解，代表了从简单的状态跟踪方法的重要进化。 概述 该服务器提供了一种设计用于解决复杂问题的高级sequentialthinking工具。与其前身不同，此版本采用真正的多智能体系统（MAS）架构，其中： 协调智能体（在coordinate模式下的Team对象）管理工作流程。 专门化智能体（计划者、研究员、分析者、评论者、综合者）根据其定义的角色和专长处理特定子任务。 进来的想法由智能体团队主动处理、分析和综合，而不仅仅是记录。 该系统支持复杂的思想模式，包括对先前步骤的修订以及探索替代路径的分支。 通过研究员智能体集成外部工具如Exa，允许动态收集信息。 强大的Pydantic验证确保思想步骤的数据完整性。 详细的日志记录跟踪整个过程，包括智能体之间的交互（由协调者处理）。 目标是通过利用协作工作的专门角色，实现比单一智能体或简单状态跟踪更高的分析质量和更细致的思维过程。 与原始版本（TypeScript）的主要区别 这个Python/Agno实现标志着与原始TypeScript版本的根本转变： 特性/方面Python/Agno 版本 (当前)TypeScript 版本 (原始)架构多代理系统 (MAS); 由一组代理主动处理。单一类状态跟踪器; 简单的日志记录/存储。智能分布式代理逻辑; 嵌入在专门的代理和协调者中。仅外部大语言模型; 没有内部智能。处理主动分析与合成; 代理对想法采取行动。被动日志记录; 仅仅记录了想法。框架Agno (MAS) + FastMCP (服务器); 使用专用的 MAS 库。仅 MCP SDK。协调明确的团队协调逻辑 (Team 在 coordinate 模式下)。无; 没有协调概念。验证Pydantic 模式验证; 强大的数据验证。基本类型检查; 可靠性较低。外部工具集成 (通过研究员使用 Exa); 可以执行研究任务。无。日志记录结构化的 Python 日志记录 (文件 + 控制台); 可配置。使用 Chalk 的控制台日志记录; 基本。语言与生态系统Python; 利用 Python 的 AI/ML 生态系统。TypeScript/Node.js。 本质上，系统从一个被动的思想记录者演变为一个由协作的 AI 代理团队驱动的主动思想处理器。 工作原理 (协调模式) 启动： 外部LLM使用sequential-thinking-starter提示来定义问题并启动流程。 工具调用： LLM使用结构化的ThoughtData Pydantic模型，通过第一个（或后续的）想法调用sequentialthinking工具。 验证与日志记录： 该工具接收调用，使用Pydantic验证输入，记录接收到的想法，并通过AppContext更新历史/分支状态。 协调器调用： 核心想法内容（连同修订/分支的相关上下文）被传递给SequentialThinkingTeam的arun方法。 协调器分析与委派： Team（作为协调者）分析输入的想法，将其分解为子任务，并将这些子任务委派给最相关的专业代理（例如，分析任务委派给Analyzer，信息需求委派给Researcher）。 专业执行： 被委派的代理使用其指令、模型和工具（如ThinkingTools或ExaTools）执行特定的子任务。 响应收集： 专家将结果返回给协调者。 综合与指导： 协调者将专家们的响应综合成一个单一且连贯的输出。此输出可能包括基于专家发现的修订或分支建议（特别是来自Critic和Analyzer）。它还为LLM提供了关于如何构思下一个想法的指导。 返回值： 该工具返回一个JSON字符串，其中包含协调者的综合响应、状态以及更新后的上下文（分支、历史长度）。 迭代： 调用的LLM利用协调者的响应和指导来形成下一次sequentialthinking工具调用，根据建议可能触发修订或分支。 令牌消耗警告 ⚠️ 高令牌使用量： 由于多代理系统架构，此工具相比单代理替代方案或之前的TypeScript版本会消耗显著更多的令牌。每次sequentialthinking调用都会涉及： 协调代理（即Team本身）。 多个专业代理（根据协调者的委派，可能是Planner、Researcher、Analyzer、Critic、Synthesizer等）。 这种并行处理导致每步思考的令牌使用量比单代理或状态跟踪方法高出许多（可能是3-6倍甚至更多）。请相应地规划预算。此工具优先考虑分析深度和质量而非令牌效率。 前提条件 Python 3.10+ 访问兼容的LLM API（配置为agno）。系统当前支持： Groq: 需要 GROQ_API_KEY。 DeepSeek: 需要 DEEPSEEK_API_KEY。 OpenRouter: 需要 OPENROUTER_API_KEY。 使用 LLM_PROVIDER 环境变量配置所需的提供者（默认为 deepseek）。 Exa API Key（仅在使用Researcher代理的功能时需要） 通过 EXA_API_KEY 环境变量设置。 uv 包管理器（推荐）或 pip。 MCP 服务器配置（客户端） 此服务器作为标准可执行脚本运行，通过stdio进行通信，如MCP所预期。具体的配置方法取决于您的具体MCP客户端实现。请参阅您客户端的文档以了解如何集成外部工具服务器的详细信息。 在您的MCP客户端配置中的 env 部分应包括您选择的 LLM_PROVIDER 的API密钥。 \{ "mcpServers": \{ "mas-sequential-thinking": \{ "command": "uvx", // Or "python", "path/to/venv/bin/python" etc. "args": [ "mcp-server-mas-sequential-thinking" // Or the path to your main script, e.g., "main.py" ], "env": \{ "LLM_PROVIDER": "deepseek", // Or "groq", "openrouter" // "GROQ_API_KEY": "your_groq_api_key", // Only if LLM_PROVIDER="groq" "DEEPSEEK_API_KEY": "your_deepseek_api_key", // Default provider // "OPENROUTER_API_KEY": "your_openrouter_api_key", // Only if LLM_PROVIDER="openrouter" "DEEPSEEK_BASE_URL": "your_base_url_if_needed", // Optional: If using a custom endpoint for DeepSeek "EXA_API_KEY": "your_exa_api_key" // Only if using Exa \} \} \} \} 安装与设置 Clone the repository: git clone git@github.com:FradSer/mcp-server-mas-sequential-thinking.git cd mcp-server-mas-sequential-thinking Set Environment Variables: Create a .env file in the project root directory or export the variables directly into your environment: # --- LLM Configuration --- # Select the LLM provider: "deepseek" (default), "groq", or "openrouter" LLM_PROVIDER="deepseek" # Provide the API key for the chosen provider: # GROQ_API_KEY="your_groq_api_key" DEEPSEEK_API_KEY="your_deepseek_api_key" # OPENROUTER_API_KEY="your_openrouter_api_key" # Optional: Base URL override (e.g., for custom DeepSeek endpoints) # DEEPSEEK_BASE_URL="your_base_url_if_needed" # Optional: Specify different models for Team Coordinator and Specialist Agents # Defaults are set within the code based on the provider if these are not set. # Example for Groq: # GROQ_TEAM_MODEL_ID="llama3-70b-8192" # GROQ_AGENT_MODEL_ID="llama3-8b-8192" # Example for DeepSeek: # DEEPSEEK_TEAM_MODEL_ID="deepseek-chat" # Note: \`deepseek-reasoner\` is not recommended as it doesn't support function calling # DEEPSEEK_AGENT_MODEL_ID="deepseek-chat" # Recommended for specialists # Example for OpenRouter: # OPENROUTER_TEAM_MODEL_ID="deepseek/deepseek-r1" # Example, adjust as needed # OPENROUTER_AGENT_MODEL_ID="deepseek/deepseek-chat" # Example, adjust as needed # --- External Tools --- # Required ONLY if the Researcher agent is used and needs Exa EXA_API_KEY="your_exa_api_key" Note on Model Selection: The TEAM_MODEL_ID is used by the Coordinator (Team object). This role benefits from strong reasoning, synthesis, and delegation capabilities. Consider using a more powerful model (e.g., deepseek-chat, claude-3-opus, gpt-4-turbo) here, potentially balancing capability with cost/speed. The AGENT_MODEL_ID is used by the specialist agents (Planner, Researcher, etc.). These handle focused sub-tasks. A faster or more cost-effective model (e.g., deepseek-chat, claude-3-sonnet, llama3-8b) might be suitable, depending on task complexity and budget/performance needs. Defaults are provided in the code (e.g., in main.py) if these environment variables are not set. Experimentation is encouraged to find the optimal balance for your use case. Install Dependencies: It's highly recommended to use a virtual environment. Using uv (Recommended): # Install uv if you don't have it: # curl -LsSf https://astral.sh/uv/install.sh | sh # source $HOME/.cargo/env # Or restart your shell # Create and activate a virtual environment (optional but recommended) python -m venv .venv source .venv/bin/activate # On Windows use \`.venv\\Scripts\\activate\` # Install dependencies uv pip install -r requirements.txt # Or if a pyproject.toml exists with dependencies defined: # uv pip install . Using pip: # Create and activate a virtual environment (optional but recommended) python -m venv .venv source .venv/bin/activate # On Windows use \`.venv\\Scripts\\activate\` # Install dependencies pip install -r requirements.txt # Or if a pyproject.toml exists with dependencies defined: # pip install . 使用方法 确保您的环境变量已设置，并且虚拟环境（如果使用）已激活。 运行服务器。请选择以下方法之一： 使用 uv run（推荐）: uv --directory /path/to/mcp-server-mas-sequential-thinking run mcp-server-mas-sequential-thinking 直接使用 Python: python main.py 服务器将启动并通过 stdio 监听请求，使配置为使用它的兼容 MCP 客户端可以使用 sequentialthinking 工具。 sequentialthinking 工具参数 该工具期望与 ThoughtData Pydantic 模型匹配的参数： # Simplified representation from src/models.py class ThoughtData(BaseModel): thought: str # Content of the current thought/step thoughtNumber: int # Sequence number (>=1) totalThoughts: int # Estimated total steps (>=1, suggest >=5) nextThoughtNeeded: bool # Is another step required after this? isRevision: bool = False # Is this revising a previous thought? revisesThought: Optional[int] = None # If isRevision, which thought number? branchFromThought: Optional[int] = None # If branching, from which thought? branchId: Optional[str] = None # Unique ID for the new branch being created needsMoreThoughts: bool = False # Signal if estimate is too low before last step 与工具交互（概念示例） 一个 LLM 将迭代地与该工具交互： LLM: 使用带有问题定义的启动提示（如 sequential-thinking-starter）。 LLM: 调用 sequentialthinking 工具，传入 thoughtNumber: 1、初始 thought（例如，“计划分析...”）、估计的 totalThoughts 和 nextThoughtNeeded: True。 服务器: MAS 处理思考。协调器综合专家的响应并提供指导（例如，“分析计划完成。建议接下来研究 X。目前不建议修改。”）。 LLM: 接收到包含 coordinatorResponse 的 JSON 响应。 LLM: 根据 coordinatorResponse 制定下一个思考（例如，“使用可用工具研究 X...”）。 LLM: 调用 sequentialthinking 工具，传入 thoughtNumber: 2、新的 thought、可能更新的 totalThoughts 和 nextThoughtNeeded: True。 服务器: MAS 处理。协调器综合（例如，“研究完成。发现表明第 1 个思考的假设存在缺陷。建议：修改第 1 个思考...”）。 LLM: 接收响应，注意建议。 LLM: 制定修订思考。 LLM: 调用 sequentialthinking 工具，传入 thoughtNumber: 3、修订 thought、isRevision: True、revisesThought: 1 和 nextThoughtNeeded: True。 ... 以此类推，根据需要可能会分支或扩展过程。 工具响应格式 工具返回一个包含以下内容的 JSON 字符串： \{ "processedThoughtNumber": int, // The thought number that was just processed "estimatedTotalThoughts": int, // The current estimate of total thoughts "nextThoughtNeeded": bool, // Whether the process indicates more steps are needed "coordinatorResponse": "...", // Synthesized output from the agent team, including analysis, findings, and guidance for the next step. "branches": ["main", "branch-id-1"], // List of active branch IDs "thoughtHistoryLength": int, // Total number of thoughts processed so far (across all branches) "branchDetails": \{ "currentBranchId": "main", // The ID of the branch the processed thought belongs to "branchOriginThought": null | int, // The thought number where the current branch diverged (null for 'main') "allBranches": \{ // Count of thoughts in each active branch "main": 5, "branch-id-1": 2 \} \}, "isRevision": bool, // Was the processed thought a revision? "revisesThought": null | int, // Which thought number was revised (if isRevision is true) "isBranch": bool, // Did this thought start a new branch? "status": "success | validation_error | failed", // Outcome status "error": null | "Error message..." // Error details if status is not 'success' \} 日志记录 默认情况下，日志写入到 ~/.sequential_thinking/logs/sequential_thinking.log。（在日志设置代码中可能可调整配置）。 使用 Python 的标准 logging 模块。 包括一个循环文件处理器（例如，10MB 限制，5 个备份）和一个控制台处理器（通常为 INFO 级别）。 日志包括时间戳、级别、记录器名称和消息，包括正在处理的思考的结构化表示。 开发 克隆仓库：（如安装步骤所示） git clone git@github.com:FradSer/mcp-server-mas-sequential-thinking.git cd mcp-server-mas-sequential-thinking 设置虚拟环境：（推荐） python -m venv .venv source .venv/bin/activate # 在 Windows 上使用 \`.venv\\Scripts\\activate\` 安装依赖（包括开发依赖）： 确保你的 requirements-dev.txt 或 pyproject.toml 指定了开发工具（例如 pytest、ruff、black、mypy）。 # 使用 uv uv pip install -r requirements.txt uv pip install -r requirements-dev.txt # 如果在 pyproject.toml 中定义了额外的依赖，则使用：uv pip install -e ".[dev]" # 使用 pip pip install -r requirements.txt pip install -r requirements-dev.txt # 如果在 pyproject.toml 中定义了额外的依赖，则使用：pip install -e ".[dev]" 运行检查： 执行代码检查器、格式化工具和测试（根据你的项目配置调整命令）。 # 示例命令（请替换为项目中实际使用的命令） ruff check . --fix black . mypy . pytest 贡献： （考虑添加贡献指南：分支策略、拉取请求流程、代码风格）。 许可证 MIT