多代理智能问答系统

👤 사용자 질의
      ⬇️
🔍 Query Analyzer Agent
   • 의도 분석 (검색, 분석, 비교, 생성 등)
   • 키워드 추출 및 엔티티 인식
   • 데이터 소스 추천
   • 7개 카테고리, 6개 패턴 인식
      ⬇️
🔧 Query Executor Agent
   • 실행 계획 생성
   • 4개 데이터 소스 통합 쿼리
   • 안전성 검증 및 결과 수집
      ⬇️
✍️ Response Generator Agent
   • 6개 템플릿 기반 자연어 생성
   • 다양한 형식 지원 (자연어, 표, JSON)
   • 소스 인용 및 신뢰도 계산
      ⬇️
🎭 Orchestrator Agent
   • 전체 파이프라인 조율
   • 세션 관리 및 성능 모니터링
   • 오류 복구 및 리소스 관리
      ⬇️
📝 최종 답변 (평균 신뢰도 92%, 처리시간 < 0.01초)

mcp/
├── core/                        # 핵심 모듈
│   ├── models.py               # 17개 Pydantic 데이터 모델
│   ├── interfaces.py           # 7개 추상 인터페이스
│   └── config.py               # 환경 설정 및 샘플 데이터
├── agents/                      # 4개 전문 에이전트
│   ├── query_analyzer/         # 질의 분석 에이전트
│   │   ├── agent.py           # 키워드 추출, 의도 분류
│   │   ├── mcp_server.py      # MCP 서버 래퍼
│   │   └── __init__.py        # 패키지 초기화
│   ├── query_executor/         # 쿼리 실행 에이전트
│   │   ├── agent.py           # 실행 계획 및 쿼리
│   │   ├── data_sources.py    # 4개 데이터 소스 구현
│   │   ├── mcp_server.py      # MCP 서버 래퍼
│   │   └── __init__.py        # 패키지 초기화
│   ├── response_generator/     # 응답 생성 에이전트
│   │   ├── agent.py           # 템플릿 기반 응답 생성
│   │   ├── mcp_server.py      # MCP 서버 래퍼
│   │   └── __init__.py        # 패키지 초기화
│   ├── orchestrator/           # 오케스트레이터
│   │   ├── agent.py           # 파이프라인 조율 로직
│   │   ├── mcp_server.py      # MCP 서버 래퍼
│   │   └── __init__.py        # 패키지 초기화
│   └── __init__.py             # 에이전트 패키지 초기화
├── api/                         # FastAPI 웹 인터페이스
│   ├── models/                 # API 요청/응답 모델
│   │   ├── requests.py        # 4개 요청 모델
│   │   ├── responses.py       # 7개 응답 모델
│   │   └── __init__.py        # 모델 패키지 초기화
│   ├── routes/
│   │   └── agents.py          # 10개 API 엔드포인트
│   └── main.py                # FastAPI 애플리케이션
├── app/                         # 애플리케이션 모듈
│   └── core/                   # 추가 핵심 기능
├── docker/                      # Docker 설정 파일들
├── data/                        # 파일 시스템 데이터 소스
├── tests/                       # 테스트 프레임워크
├── .env                         # 환경 변수 설정
├── run_api.py                   # API 서버 실행 스크립트
├── run_mcp_servers.py          # MCP 서버 관리자
├── test_agents.py              # 에이전트 단위 테스트
├── test_system.py              # 통합 시스템 테스트
├── requirements.txt            # 의존성 패키지 목록
└── pyproject.toml              # 프로젝트 메타데이터

cd /mnt/d/IdeaProjects/mcp
pip install -r requirements.txt

# Docker Compose로 전체 스택 실행
cd /mnt/d/IdeaProjects/mcp
docker compose up -d

# 개별 서비스만 실행
docker compose up app          # API 서버만
docker compose up postgres     # PostgreSQL만
docker compose up kafka        # Kafka 스택만

# 개별 에이전트 테스트
python test_agents.py
# 결과: 4/4 통과, 모든 에이전트 정상 작동

# 통합 시스템 테스트 (API 서버를 먼저 실행해야 함)
python run_api.py &           # 백그라운드에서 API 서버 실행
python test_system.py         # 시스템 테스트 실행
# 결과: 5/5 통과, 성공률 100%

python run_api.py

# 전체 스택 실행 (권장)
docker compose up -d

# 서비스 상태 확인
docker compose ps

# 로그 확인
docker compose logs -f app

curl -X POST http://localhost:8000/agents/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "부서별 평균 급여를 분석해줘",
    "context": {"user_id": "analyst_001"},
    "preferences": {
      "response_format": "natural",
      "include_sources": true
    }
  }'

{
  "success": true,
  "processing_time": 0.0008,
  "session_id": "abc123",
  "final_response": {
    "response_text": "분석 결과\n\n질문: 부서별 평균 급여를 분석해줘\n\n분석을 수행한 결과는 다음과 같습니다:\n\n📊 데이터베이스 (users) - 3개 레코드\n  • Engineering: 80,000원\n  • Sales: 75,000원\n  • Marketing: 70,000원\n\n📊 주요 인사이트:\n• 평균 급여: 75,000원\n• 최고 급여 부서: Engineering (80,000원)\n• 급여 편차: 10,000원\n\n총 1개의 데이터 소스에서 검색을 수행했습니다.",
    "confidence_score": 0.9,
    "sources_used": ["database"],
    "generation_time": 0.0001
  }
}

curl -X POST http://localhost:8000/agents/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI와 머신러닝의 차이점을 설명해줘"
  }'

curl http://localhost:8000/agents/health

data/                    # 파일 시스템 데이터 소스
├── documents/          # 문서 파일
├── logs/              # 시스템 로그
└── exports/           # 내보낸 결과

{
  "servers": {
    "multi-agent-system": {
      "command": "python",
      "args": ["run_mcp_servers.py", "4"],
      "cwd": "/mnt/d/IdeaProjects/mcp"
    }
  }
}

# 사용 가능한 서버 목록
python run_mcp_servers.py list

# 특정 서버 실행
python run_mcp_servers.py 1    # Query Analyzer
python run_mcp_servers.py 2    # Query Executor
python run_mcp_servers.py 3    # Response Generator
python run_mcp_servers.py 4    # Orchestrator (권장)

# agents/query_executor/data_sources.py에 추가
class CustomDataSource(DataSourceInterface):
    async def connect(self) -> bool:
        # 연결 로직 구현
        pass

    async def query(self, query_params: Dict[str, Any]) -> Dict[str, Any]:
        # 쿼리 실행 로직 구현
        pass

# agents/response_generator/agent.py에서 템플릿 수정
templates = {
    "custom": "사용자 정의 템플릿: {query}\n결과: {results}"
}

export PORT=8001 && python run_api.py

pip install --upgrade -r requirements.txt

# 개별 에이전트만 실행
python run_mcp_servers.py 1

# 디버그 모드로 실행
export DEBUG=true LOG_LEVEL=DEBUG
python run_api.py

# 에이전트별 테스트
python test_agents.py analyzer     # 분석 에이전트만
python test_agents.py executor     # 실행 에이전트만
python test_agents.py generator    # 생성 에이전트만
python test_agents.py orchestrator # 오케스트레이터만

# 시스템 상태
curl http://localhost:8000/health

# 에이전트 상태
curl http://localhost:8000/agents/health

# 성능 메트릭
curl http://localhost:8000/agents/metrics

# 개발 의존성 설치
pip install -r requirements.txt

# 코드 스타일 검사
python -m flake8 agents/ api/ core/

# 타입 검사
python -m mypy agents/ api/ core/

# 전체 테스트
python test_agents.py && python test_system.py

# 성능 테스트
time python test_system.py