Sistema multiagente de pensamiento secuencial (MAS)

Inglés | Chino tradicional

Este proyecto implementa un proceso avanzado de pensamiento secuencial mediante un Sistema Multiagente (MAS) desarrollado con el framework Agno y gestionado mediante MCP . Representa una evolución significativa respecto a los enfoques más sencillos de seguimiento de estados, al aprovechar agentes coordinados y especializados para un análisis más profundo y la descomposición de problemas.

Descripción general

Este servidor proporciona una sofisticada herramienta sequentialthinking diseñada para la resolución de problemas complejos. A diferencia de su predecesor , esta versión utiliza una verdadera arquitectura de Sistema Multiagente (MAS) donde:

• Un agente coordinador (el objeto Team en modo coordinate ) administra el flujo de trabajo.

• Los agentes especializados (planificador, investigador, analizador, crítico, sintetizador) manejan subtareas específicas según sus roles y experiencia definidos.

• El equipo de agentes procesa, analiza y sintetiza activamente los pensamientos entrantes, no solo los registra.

• El sistema admite patrones de pensamiento complejos, incluidas revisiones de pasos anteriores y ramificaciones para explorar caminos alternativos.

• La integración con herramientas externas como Exa (a través del agente Researcher) permite la recopilación de información dinámica.

• La sólida validación de Pydantic garantiza la integridad de los datos durante todos los pasos del proceso.

• El registro detallado rastrea el proceso, incluidas las interacciones de los agentes (gestionadas por el coordinador).

El objetivo es lograr una mayor calidad de análisis y un proceso de pensamiento más matizado que el que es posible con un solo agente o un simple seguimiento de estados aprovechando el poder de roles especializados que trabajan en colaboración.

Related MCP server: Sequential-Thinking

Diferencias clave con respecto a la versión original (TypeScript)

Esta implementación de Python/Agno marca un cambio fundamental con respecto a la versión original de TypeScript:

En esencia, el sistema evolucionó desde un registrador de pensamientos pasivo a un procesador de pensamientos activo impulsado por un equipo colaborativo de agentes de IA.

Cómo funciona (modo de coordenadas)

1. Iniciación: un LLM externo utiliza el mensaje sequential-thinking-starter para definir el problema e iniciar el proceso.

2. Llamada de herramienta: El LLM llama a la herramienta sequentialthinking con el primer pensamiento (o subsiguiente), estructurado de acuerdo con el modelo Pydantic ThoughtData .

3. Validación y registro: la herramienta recibe la llamada, valida la entrada usando Pydantic, registra el pensamiento entrante y actualiza el historial/estado de la rama a través de AppContext .

4. Invocación del coordinador: el contenido del pensamiento central (junto con el contexto sobre las revisiones/ramas) se pasa al método arun del SequentialThinkingTeam .

5. Análisis y delegación del coordinador: el Team (que actúa como coordinador) analiza el pensamiento de entrada, lo divide en subtareas y delega estas subtareas a los agentes especializados más relevantes (por ejemplo, el analizador para las tareas de análisis, el investigador para las necesidades de información).

6. Ejecución especializada: los agentes delegados ejecutan sus subtareas específicas utilizando sus instrucciones, modelos y herramientas (como ThinkingTools o ExaTools ).

7. Recopilación de respuestas: Los especialistas devuelven sus resultados al Coordinador.

8. Síntesis y orientación: El coordinador sintetiza las respuestas de los especialistas en un resultado único y coherente. Este resultado puede incluir recomendaciones de revisión o ramificación basadas en las conclusiones de los especialistas (especialmente del crítico y el analista). También proporciona orientación al LLM para formular la siguiente idea.

9. Valor de retorno: la herramienta devuelve una cadena JSON que contiene la respuesta sintetizada del Coordinador, el estado y el contexto actualizado (ramas, longitud del historial).

10. Iteración: el LLM que realiza la llamada utiliza la respuesta y la guía del Coordinador para formular la siguiente llamada a la herramienta de sequentialthinking , lo que potencialmente desencadena revisiones o ramas según lo sugerido.

Advertencia sobre el consumo de tokens

Alto consumo de tokens: Gracias a la arquitectura del sistema multiagente, esta herramienta consume muchos más tokens que las alternativas de un solo agente o la versión anterior de TypeScript. Cada llamada sequentialthinking invoca:

• El agente Coordinador (el Team en sí).

• Múltiples agentes especialistas (potencialmente Planificador, Investigador, Analizador, Crítico, Sintetizador, dependiendo de la delegación del Coordinador).

Este procesamiento paralelo genera un uso de tokens considerablemente mayor (potencialmente de 3 a 6 veces o más por paso de pensamiento) en comparación con los enfoques de agente único o de seguimiento de estado. Planifique y calcule el presupuesto en consecuencia. Esta herramienta prioriza la profundidad y la calidad del análisis sobre la eficiencia de los tokens.

Prerrequisitos

• Python 3.10+

• Acceso a una API LLM compatible (configurada para agno ). El sistema actualmente admite:

  • Groq: Requiere GROQ_API_KEY .

  • DeepSeek: requiere DEEPSEEK_API_KEY .

  • OpenRouter: requiere OPENROUTER_API_KEY .

  • Configure el proveedor deseado utilizando la variable de entorno LLM_PROVIDER (predeterminada en deepseek ).

• Clave API de Exa (requerida solo si se utilizan las capacidades del agente Investigador)

  • Se establece a través de la variable de entorno EXA_API_KEY .

• Gestor de paquetes uv (recomendado) o pip .

Configuración del servidor MCP (lado del cliente)

Este servidor se ejecuta como un script ejecutable estándar que se comunica mediante stdio, como lo espera MCP. El método de configuración exacto depende de la implementación específica de su cliente MCP. Consulte la documentación de su cliente para obtener más información sobre la integración de servidores de herramientas externos.

La sección env dentro de la configuración de su cliente MCP debe incluir la clave API para el LLM_PROVIDER elegido.

{
  "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
         }
      }
   }
}

Instalación y configuración

Instalación mediante herrería

Para instalar automáticamente el sistema multiagente de pensamiento secuencial para Claude Desktop a través de Smithery :

npx -y @smithery/cli install @FradSer/mcp-server-mas-sequential-thinking --client claude

Instalación manual

1. Clonar el repositorio:

   git clone git@github.com:FradSer/mcp-server-mas-sequential-thinking.git
   cd mcp-server-mas-sequential-thinking

2. Establecer variables de entorno: cree un archivo .env en el directorio raíz del proyecto o exporte las variables directamente a su entorno:

   # --- 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"

   Nota sobre la selección del modelo:

   • El TEAM_MODEL_ID lo utiliza el Coordinador (objeto Team ). Este rol se beneficia de sólidas capacidades de razonamiento, síntesis y delegación. Considere usar un modelo más potente (p. ej., deepseek-chat , claude-3-opus , gpt-4-turbo ), para equilibrar la capacidad con el costo y la velocidad.

   • El AGENT_MODEL_ID lo utilizan los agentes especializados (Planificador, Investigador, etc.). Estos gestionan subtareas específicas. Un modelo más rápido o rentable (p. ej., deepseek-chat , claude-3-sonnet , llama3-8b ) podría ser adecuado, dependiendo de la complejidad de la tarea y las necesidades de presupuesto y rendimiento.

   • Si estas variables de entorno no están configuradas, se proporcionan valores predeterminados en el código (p. ej., en main.py ). Se recomienda experimentar para encontrar el equilibrio óptimo para su caso de uso.

3. Instalar dependencias: es muy recomendable utilizar un entorno virtual.

   • Uso de uv (recomendado):

     # 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 .

   • Usando 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 .

Uso

Asegúrese de que las variables de entorno estén configuradas y que el entorno virtual (si se utiliza) esté activo.

Ejecute el servidor. Elija uno de los siguientes métodos:

1. Uso de uv run (recomendado):

   uv --directory /path/to/mcp-server-mas-sequential-thinking run mcp-server-mas-sequential-thinking

2. Usando Python directamente:

   python main.py

El servidor se iniciará y escuchará solicitudes a través de stdio, lo que hará que la herramienta sequentialthinking esté disponible para los clientes MCP compatibles configurados para usarla.

Parámetros de la herramienta sequentialthinking

La herramienta espera argumentos que coincidan con el modelo Pydantic ThoughtData :

# 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

Interactuando con la herramienta (Ejemplo conceptual)

Un LLM interactuaría con esta herramienta de forma iterativa:

1. LLM: utiliza un mensaje inicial (como sequential-thinking-starter ) con la definición del problema.

2. LLM: Llama a la herramienta sequentialthinking con thoughtNumber: 1 , el thought inicial (por ejemplo, "Planifique el análisis..."), un totalThoughts estimado de Thoughts y nextThoughtNeeded: True .

3. Servidor: El MAS procesa la idea. El Coordinador sintetiza las respuestas de los especialistas y ofrece orientación (p. ej., "Plan de análisis completo. Sugiero investigar X a continuación. No se recomiendan revisiones todavía").

4. LLM: recibe la respuesta JSON que contiene coordinatorResponse .

5. LLM: Formula el siguiente pensamiento basándose en la coordinatorResponse (por ejemplo, "Investiga X usando las herramientas disponibles...").

6. LLM: Llama a la herramienta sequentialthinking con thoughtNumber: 2 , el nuevo thought , potencialmente actualizado totalThoughts , nextThoughtNeeded: True .

7. Servidor: Procesos MAS. El Coordinador sintetiza (p. ej., "Investigación completa. Los hallazgos sugieren una falla en la suposición de la idea n.° 1. RECOMENDACIÓN: Revisar la idea n.° 1...").

8. LLM: Recibe la respuesta, toma nota de la recomendación.

9. LLM: Formula un pensamiento de revisión.

10. LLM: Llama a la herramienta sequentialthinking con thoughtNumber: 3 , el thought de revisión, isRevision: True , revisesThought: 1 , nextThoughtNeeded: True .

11. ...y así sucesivamente, ramificando o ampliando potencialmente el proceso según sea necesario.

Formato de respuesta de la herramienta

La herramienta devuelve una cadena JSON que contiene:

{
  "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'
}

Explotación florestal

• Los registros se escriben en ~/.sequential_thinking/logs/sequential_thinking.log de forma predeterminada. (La configuración se puede ajustar en el código de configuración del registro).

• Utiliza el módulo logging estándar de Python.

• Incluye un controlador de archivos rotativo (por ejemplo, límite de 10 MB, 5 copias de seguridad) y un controlador de consola (normalmente de nivel INFO).

• Los registros incluyen marcas de tiempo, niveles, nombres de registradores y mensajes, incluidas representaciones estructuradas de los pensamientos que se están procesando.

Desarrollo

1. Clonar el repositorio: (Como en la Instalación)

   git clone git@github.com:FradSer/mcp-server-mas-sequential-thinking.git
   cd mcp-server-mas-sequential-thinking

2. Configurar entorno virtual: (recomendado)

   python -m venv .venv
   source .venv/bin/activate # On Windows use `.venv\\Scripts\\activate`

3. Instalar dependencias (incluido dev): asegúrese de que su requirements-dev.txt o pyproject.toml especifique herramientas de desarrollo (como pytest , ruff , black , mypy ).

   # Using uv
   uv pip install -r requirements.txt
   uv pip install -r requirements-dev.txt # Or install extras if defined in pyproject.toml: uv pip install -e ".[dev]"
   
   # Using pip
   pip install -r requirements.txt
   pip install -r requirements-dev.txt # Or install extras if defined in pyproject.toml: pip install -e ".[dev]"

4. Ejecutar comprobaciones: ejecuta linters, formateadores y pruebas (adapta los comandos según la configuración de tu proyecto).

   # Example commands (replace with actual commands used in the project)
   ruff check . --fix
   black .
   mypy .
   pytest

5. Contribución: (Considere agregar pautas de contribución: estrategia de ramificación, proceso de solicitud de extracción, estilo de código).

Licencia

Instituto Tecnológico de Massachusetts (MIT)