순차적 사고 다중 에이전트 시스템(MAS)

영어 | 간체 중국어

이 프로젝트는 Agno 프레임워크로 구축되고 MCP 를 통해 제공되는 다중 에이전트 시스템(MAS)을 사용하여 고급 순차적 사고 프로세스를 구현합니다. 이는 심층 분석 및 문제 분해를 위해 조정되고 특화된 에이전트를 활용함으로써 단순한 상태 추적 방식에서 크게 발전한 것을 보여줍니다.

개요

이 서버는 복잡한 문제 해결을 위해 설계된 정교한 sequentialthinking 도구를 제공합니다. 이전 버전 과 달리, 이 버전은 다음과 같은 특징을 갖춘 진정한 다중 에이전트 시스템(MAS) 아키텍처를 활용합니다.

• 조정 에이전트 ( coordinate 모드에서는 Team 객체)는 워크플로를 관리합니다.

• 전문 에이전트 (기획자, 연구자, 분석가, 비평가, 합성가)는 정의된 역할과 전문성에 따라 특정 하위 작업을 처리합니다.

• 에이전트 팀은 들어오는 생각을 단순히 기록하는 데 그치지 않고 적극적으로 처리, 분석, 종합합니다 .

• 이 시스템은 이전 단계를 수정하고 대체 경로를 탐색하기 위한 분기 를 포함한 복잡한 사고 패턴을 지원합니다.

• Exa (Researcher 에이전트를 통해)와 같은 외부 도구와 통합하면 동적으로 정보를 수집할 수 있습니다.

• 강력한 Pydantic 검증을 통해 사고 단계에 대한 데이터 무결성이 보장됩니다.

• 자세한 로깅은 코디네이터가 처리하는 에이전트 상호작용을 포함한 프로세스를 추적합니다.

목표는 단일 에이전트나 단순한 상태 추적으로는 불가능한, 전문화된 역할의 협업적 작업을 통해 더 높은 품질의 분석과 더 섬세한 사고 과정을 달성하는 것입니다.

Related MCP server: Sequential-Thinking

원본 버전(TypeScript)과의 주요 차이점

이 Python/Agno 구현은 원래 TypeScript 버전과 근본적으로 다른 점을 보여줍니다.

본질적으로, 이 시스템은 수동적인 사고 기록기 에서 AI 에이전트로 구성된 협업 팀에 의해 구동되는 능동적인 사고 처리기 로 진화했습니다.

작동 원리(좌표 모드)

1. 개시: 외부 LLM은 sequential-thinking-starter 프롬프트를 사용하여 문제를 정의하고 프로세스를 개시합니다.

2. 도구 호출: LLM은 ThoughtData Pydantic 모델에 따라 구조화된 첫 번째(또는 그 이후의) 사고로 sequentialthinking 도구를 호출합니다.

3. 검증 및 로깅: 도구는 호출을 받고 Pydantic을 사용하여 입력을 검증하고, 들어오는 생각을 로깅하고, AppContext 통해 기록/분기 상태를 업데이트합니다.

4. 코디네이터 호출: 핵심 사고 내용(개정/분기에 대한 컨텍스트와 함께)은 SequentialThinkingTeam 의 arun 메서드로 전달됩니다.

5. 코디네이터 분석 및 위임: Team (코디네이터 역할)은 입력된 사고를 분석하고, 이를 하위 작업으로 나누고, 이러한 하위 작업을 가장 관련성이 높은 전문가 에이전트(예: 분석 작업을 위한 분석가, 정보 요구 사항을 위한 연구원)에게 위임합니다.

6. 전문가 실행: 위임된 에이전트는 각자의 지침, 모델, 도구( ThinkingTools 또는 ExaTools 등)를 사용하여 특정 하위 작업을 실행합니다.

7. 응답 수집: 전문가가 결과를 코디네이터에게 반환합니다.

8. 종합 및 지침: 코디네이터는 전문가들의 답변을 하나의 응집력 있는 결과물로 종합합니다. 이 결과물에는 전문가의 결과(특히 비평가와 분석가의 결과)를 바탕으로 수정 또는 분기화에 대한 권고가 포함될 수 있습니다. 또한 LLM에게 다음 아이디어를 구체화하는 데 필요한 지침을 제공합니다.

9. 반환 값: 이 도구는 코디네이터의 합성 응답, 상태, 업데이트된 컨텍스트(분기, 기록 길이)를 포함하는 JSON 문자열을 반환합니다.

10. 반복: 호출하는 LLM은 코디네이터의 응답과 지침을 사용하여 다음 sequentialthinking 도구 호출을 공식화하고, 제안된 대로 개정이나 분기를 유발할 가능성이 있습니다.

토큰 소비 경고

⚠️ 높은 토큰 사용량: 다중 에이전트 시스템 아키텍처로 인해 이 도구는 단일 에이전트 대안이나 이전 TypeScript 버전보다 훨씬 더 많은 토큰을 사용합니다. 각 sequentialthinking 호출은 다음을 호출합니다.

• 코디네이터 에이전트( Team 자체).

• 다수의 전문가 에이전트(조정자의 위임에 따라 기획자, 연구자, 분석가, 비평가, 합성가 등)

이러한 병렬 처리는 단일 에이전트 또는 상태 추적 방식에 비해 토큰 사용량이 상당히 높아집니다(생각 단계당 3~6배 이상). 이에 따라 예산을 책정하고 계획을 수립하십시오. 이 도구는 토큰 효율성보다 분석 심도와 품질을 우선시합니다.

필수 조건

• 파이썬 3.10+

• 호환되는 LLM API에 대한 액세스( agno 용으로 구성됨). 시스템은 현재 다음을 지원합니다.

  • Groq: GROQ_API_KEY 가 필요합니다.

  • DeepSeek: DEEPSEEK_API_KEY 가 필요합니다.

  • OpenRouter: OPENROUTER_API_KEY 가 필요합니다.

  • LLM_PROVIDER 환경 변수를 사용하여 원하는 공급자를 구성합니다(기본값은 deepseek ).

• Exa API 키(연구원 에이전트의 기능을 사용하는 경우에만 필요)

  • EXA_API_KEY 환경 변수를 통해 설정됩니다.

• uv 패키지 관리자(권장) 또는 pip .

MCP 서버 구성(클라이언트 측)

이 서버는 MCP에서 예상하는 대로 stdio를 통해 통신하는 표준 실행 가능 스크립트로 실행됩니다. 정확한 구성 방법은 특정 MCP 클라이언트 구현에 따라 다릅니다. 외부 도구 서버 통합에 대한 자세한 내용은 클라이언트 설명서를 참조하십시오.

MCP 클라이언트 구성 내의 env 섹션에는 선택한 LLM_PROVIDER 에 대한 API 키가 포함되어야 합니다.

지엑스피1

설치 및 설정

Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 Sequential Thinking Multi-Agent System을 자동으로 설치하려면:

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

수동 설치

1. 저장소를 복제합니다.

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

2. 환경 변수 설정: 프로젝트 루트 디렉토리에 .env 파일을 만들거나 변수를 환경으로 직접 내보냅니다.

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

   모델 선택에 대한 참고 사항:

   • TEAM_MODEL_ID 는 코디네이터( Team 객체)에서 사용됩니다. 이 역할은 강력한 추론, 합성 및 위임 기능을 활용합니다. 이 경우 더 강력한 모델(예: deepseek-chat , claude-3-opus , gpt-4-turbo )을 사용하여 성능과 비용/속도의 균형을 맞추는 것을 고려해 보세요.

   • AGENT_MODEL_ID 는 전문 에이전트(Planner, Researcher 등)에서 사용됩니다. 이들은 특정 하위 작업을 처리합니다. 작업의 복잡성과 예산/성능 요구 사항에 따라 더 빠르거나 비용 효율적인 모델(예: deepseek-chat , claude-3-sonnet , llama3-8b )이 적합할 수 있습니다.

   • 이러한 환경 변수가 설정되지 않은 경우 코드(예: main.py )에 기본값이 제공됩니다. 사용 사례에 가장 적합한 균형을 찾기 위해 여러 가지 방법을 시도해 보는 것이 좋습니다.

3. 종속성 설치: 가상 환경을 사용하는 것이 좋습니다.

   • uv 사용(권장):

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

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

용법

환경 변수가 설정되어 있고 가상 환경(사용하는 경우)이 활성화되어 있는지 확인하세요.

서버를 실행하세요. 다음 방법 중 하나를 선택하세요.

1. uv run 사용(권장):

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

2. Python을 직접 사용하는 경우:

   python main.py

서버가 시작되어 stdio를 통해 요청을 수신하고, 이를 통해 sequentialthinking 도구를 사용하도록 구성된 호환 MCP 클라이언트에서 해당 도구를 사용할 수 있게 됩니다.

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은 이 도구와 반복적으로 상호 작용합니다.

1. LLM: 문제 정의와 함께 시작 프롬프트(예: sequential-thinking-starter )를 사용합니다.

2. LLM: thoughtNumber: 1 , 초기 thought (예: "분석 계획..."), 추정된 totalThoughts , nextThoughtNeeded: True 사용하여 sequentialthinking 도구를 호출합니다.

3. 서버: MAS가 생각을 처리합니다. 코디네이터는 전문가들의 답변을 종합하여 지침을 제공합니다(예: "분석 계획 완료. 다음 X 조사 제안. 아직 수정 권장 없음").

4. LLM: coordinatorResponse 포함하는 JSON 응답을 수신합니다.

5. LLM: coordinatorResponse 기반으로 다음 생각을 공식화합니다(예: "사용 가능한 도구를 사용하여 X를 연구하세요...").

6. LLM: thoughtNumber: 2 , 새로운 thought , 잠재적으로 업데이트된 totalThoughts , nextThoughtNeeded: True 사용하여 sequentialthinking 도구를 호출합니다.

7. 서버: MAS 프로세스. 코디네이터는 종합합니다(예: "연구 완료. 연구 결과에 따르면 생각 #1의 가정에 결함이 있는 것으로 보입니다. 권고: 생각 #1을 수정하세요...").

8. LLM: 응답을 받고 권장 사항을 기록합니다.

9. LLM: 수정 사상을 공식화합니다.

10. LLM: thoughtNumber: 3 , thought 수정, isRevision: True , revisesThought: 1 , nextThoughtNeeded: True 를 사용하여 sequentialthinking 도구를 호출합니다.

11. ... 이런 식으로 필요에 따라 프로세스를 분기화하거나 확장할 수 있습니다.

도구 응답 형식

이 도구는 다음을 포함하는 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 수준)가 포함됩니다.

• 로그에는 타임스탬프, 수준, 로거 이름, 메시지가 포함되며, 처리되는 생각에 대한 구조화된 표현도 포함됩니다.

개발

1. 저장소를 복제합니다. (설치와 같이)

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

2. 가상 환경 설정: (권장)

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

3. 종속성 설치(dev 포함): requirements-dev.txt 또는 pyproject.toml 에 개발 도구( 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. 검사 실행: 린터, 포매터, 테스트를 실행합니다(프로젝트 설정에 따라 명령을 조정합니다).

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

5. 기여: (기여 가이드라인을 추가하는 것을 고려하세요: 분기 전략, 풀 리퀘스트 프로세스, 코드 스타일).

특허

MIT