TTimes Guide Coding - Multi-Agent Report Generation System

웹 검색과 보고서 작성을 자동화하는 LangGraph 기반 멀티 에이전트 시스템

MCP & A2A 로 실전 Multi Agents 만들어보기 프로젝트

개요

본 프로젝트는 사용자의 요청에 따라 웹 검색, 문서 검색, 보고서 계획 수립, 보고서 작성을 자동으로 수행하는 AI 멀티 에이전트 시스템입니다. LangGraph와 A2A(Agent-to-Agent) 프로토콜을 사용하여 여러 전문 에이전트들이 협력하여 고품질의 보고서를 생성합니다.

주요 기능

• 🔍 실시간 웹 검색 - Tavily Search API를 통한 최신 정보 수집
• 📚 벡터 DB 검색 - PostgreSQL pgvector를 이용한 유사 문서 검색
• 📋 자동 계획 수립 - AI 기반 작업 계획 및 구조 설계
• ✍️ 보고서 작성 - 수집된 정보를 종합한 전문적인 보고서 생성
• 🤖 MCP 통합 - Model Context Protocol을 통한 도구 통합
• 🔗 A2A 통신 - Google ADK 기반 에이전트 간 통신

Tech Stack

• Python 3.13
• LangChain - LLM 애플리케이션 프레임워크
• LangGraph - 상태 기반 AI 워크플로우
• A2A Protocol - 에이전트 간 통신 표준
• FastMCP - Model Context Protocol 서버
• Google ADK - Agent Development Kit
• FastAPI - 웹 서버
• PostgreSQL + pgvector - 벡터 데이터베이스
• Redis - 캐시 및 세션 관리
• Azure OpenAI - LLM 제공자

시스템 아키텍처

┌─────────────────────────┐
│ UnifiedResearch Agent   │ ← Google ADK 기반 오케스트레이터
│    (ADK Client)         │
└───────────┬─────────────┘
            │ A2A Protocol
    ┌───────┴───────┬──────────────┐
    ▼               ▼              ▼
┌─────────┐   ┌──────────┐   ┌──────────┐
│Planning │   │ Research │   │  Report  │
│  Agent  │   │  Agent   │   │ Writing  │
│(A2A Srv)│   │(A2A Srv) │   │(A2A Srv) │
└────┬────┘   └────┬─────┘   └──────────┘
     │             │ MCP Protocol
     │             ▼
     │      ┌──────────────┐
     │      │ All-Search   │
     │      │ MCP Server   │
     │      └───┬──────┬───┘
     │          │      │
     │          ▼      ▼
     │      [Tavily] [LangConnect]
     │                     │
     └─────────────────────┼─────────────┐
                           ▼             ▼
                    [PostgreSQL+pgvector] [Redis]

설치 방법

1. 사전 요구사항

• Python 3.13+
• Docker & Docker Compose
• uv (Python 패키지 매니저)

2. 프로젝트 클론

git clone https://github.com/yourusername/ttimes_guide_coding.git
cd ttimes_guide_coding

3. 환경 설정

# 환경 변수 파일 생성
cp .env.example .env

# .env 파일을 편집하여 필요한 API 키 입력:
# - AZURE_OPENAI_API_KEY
# - AZURE_OPENAI_ENDPOINT
# - AZURE_OPENAI_DEPLOYMENT_NAME
# - TAVILY_API_KEY
# - GOOGLE_API_KEY (ADK용)
# - 기타 설정값

4. 의존성 설치

# uv를 사용한 의존성 설치
uv sync --dev

# 또는 개발 의존성 제외
uv sync

실행 방법

1. LangConnect 시작 (벡터 DB)

cd langconnect
make up  # Docker Compose로 PostgreSQL + API 서버 시작
cd ..

2. 전체 시스템 실행

# 실행 권한 부여 (최초 1회)
chmod +x scripts/run_all_agents.sh

# 시스템 시작
./scripts/run_all_agents.sh

3. LangGraph 에이전트 개별 테스트

# LangGraph Studio로 테스트
./scripts/test_langgraph_agents.sh

4. 시스템 사용

# CLI 모드
python a2a_client/unified_research_agent.py

# 또는 API 호출
curl -X POST http://localhost:8000/research \
  -H "Content-Type: application/json" \
  -d '{"topic": "AI 트렌드 분석", "depth": "comprehensive"}'

5. 개별 A2A 서버 실행

# Planning Agent A2A Server
python agents/a2a_servers/planning_a2a_server.py

# Research Agent A2A Server  
python agents/a2a_servers/research_a2a_server.py

# Report Writing Agent A2A Server
python agents/a2a_servers/report_writing_a2a_server.py

# MCP Server
python all-search-mcp/run_server.py --transport http

API 엔드포인트

각 에이전트는 A2A 프로토콜을 따르는 엔드포인트를 제공합니다:

• UnifiedResearch Agent: http://localhost:8000
• Research Agent A2A: http://localhost:8001
• Planning Agent A2A: http://localhost:8003
• Report Writing Agent A2A: http://localhost:8004
• MCP Server: http://localhost:8090/mcp
• LangConnect API: http://localhost:8080
• LangGraph Studio: http://localhost:8123

사용 예제

Python SDK 사용

from a2a_client import UnifiedResearchAgent, ResearchRequest

# 에이전트 생성
agent = UnifiedResearchAgent()

# 연구 요청
request = ResearchRequest(
    topic="Python 웹 프레임워크 비교 분석",
    depth="comprehensive",
    output_format="markdown"
)

# 연구 수행
result = await agent.conduct_research(request)

# 결과 출력
print(result.report)

REST API 사용

curl -X POST http://localhost:8000/research \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Python 웹 프레임워크 비교 분석",
    "depth": "comprehensive"
  }'

Google ADK Web UI

# ADK 웹 UI 시작
adk web a2a_client/

개발 가이드

프로젝트 구조

ttimes_guide_coding/
├── agents/              # LangGraph 에이전트
│   ├── agent/          # 에이전트 구현체
│   ├── a2a_servers/    # A2A 서버 래퍼
│   ├── base/           # 기본 클래스
│   └── tools/          # MCP 클라이언트
├── all-search-mcp/      # MCP 서버
├── a2a_client/          # Google ADK 클라이언트
├── langconnect/         # 벡터 DB API
├── docker/              # Docker 설정
├── scripts/             # 실행 스크립트
└── docs/                # 참고 문서

새로운 LangGraph 에이전트 추가하기

1. /agents/agent/ 디렉토리에 새 에이전트 파일 생성
2. BaseAgent 클래스 상속 및 노드/엣지 구현
3. /agents/graph_builders.py에 그래프 빌더 함수 추가
4. langgraph.json에 에이전트 등록
5. A2A 서버 래퍼 구현 (optional)

MCP 도구 추가하기

1. /all-search-mcp/server.py에 새 도구 함수 추가
2. @mcp.tool() 데코레이터로 도구 정의
3. 에이전트에서 MCP 클라이언트를 통해 사용

---

MCP 서버 개발 가이드

Describing your server

Once you've provided the documentation, clearly describe to Claude what kind of server you want to build. Be specific about:

• What resources your server will expose
• What tools it will provide
• Any prompts it should offer
• What external systems it needs to interact with

For example:

Build an MCP server that:
- Connects to my company's PostgreSQL database
- Exposes table schemas as resources
- Provides tools for running read-only SQL queries
- Includes prompts for common data analysis tasks

Working with Claude

When working with Claude on MCP servers:

1. Start with the core functionality first, then iterate to add more features
2. Ask Claude to explain any parts of the code you don't understand
3. Request modifications or improvements as needed
4. Have Claude help you test the server and handle edge cases

Claude can help implement all the key MCP features:

• Resource management and exposure
• Tool definitions and implementations
• Prompt templates and handlers
• Error handling and logging
• Connection and transport setup

Best practices

When building MCP servers with Claude:

• Break down complex servers into smaller pieces
• Test each component thoroughly before moving on
• Keep security in mind - validate inputs and limit access appropriately
• Document your code well for future maintenance
• Follow MCP protocol specifications carefully

Next steps

After Claude helps you build your server:

1. Review the generated code carefully
2. Test the server with the MCP Inspector tool
3. Connect it to Claude.app or other MCP clients
4. Iterate based on real usage and feedback

---

A2A 개발 가이드

Reference

LangChain
LangConnect-Client
LangGraph
LangChain-MCP-Adapter(client)
ModelContextProtocol
MCP-Python-SDK
FastMCP
FastMCP-llms.txt
A2A-SDK
A2A-Directory

Cursor Tips

REPOMIX
CURSOR-Rules
CURSOR-RIPER-Framework