Content
# TTimes Guide Coding - Multi-Agent Report Generation System
An AI multi-agent system based on LangGraph that automates web searches and report writing.
## Overview
This project is an AI multi-agent system that automatically performs web searches, document searches, report planning, and report writing based on user requests. Utilizing LangGraph and the A2A (Agent-to-Agent) protocol, multiple specialized agents collaborate to generate high-quality reports.
## Key Features
- 🔍 **Real-time Web Search** - Collecting the latest information through the Tavily Search API
- 📚 **Vector DB Search** - Similar document search using PostgreSQL pgvector
- 📋 **Automatic Planning** - AI-based task planning and structure design
- ✍️ **Report Writing** - Generating professional reports that compile the collected information
- 🤖 **MCP Integration** - Tool integration through the Model Context Protocol
- 🔗 **A2A Communication** - Agent communication based on Google ADK
## Tech Stack
- **Python 3.13**
- **LangChain** - LLM application framework
- **LangGraph** - State-based AI workflow
- **A2A Protocol** - Standard for agent communication
- **FastMCP** - Model Context Protocol server
- **Google ADK** - Agent Development Kit
- **FastAPI** - Web server
- **PostgreSQL + pgvector** - Vector database
- **Redis** - Cache and session management
- **Azure OpenAI** - LLM provider
## System Architecture
```
┌─────────────────────────┐
│ UnifiedResearch Agent │ ← Orchestrator based on 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]
```
## Installation Instructions
### 1. Prerequisites
- Python 3.13+
- Docker & Docker Compose
- uv (Python package manager)
### 2. Clone the Project
```bash
git clone https://github.com/yourusername/ttimes_guide_coding.git
cd ttimes_guide_coding
```
### 3. Environment Setup
```bash
# Create environment variable file
cp .env.example .env
# Edit the .env file to input the required API keys:
# - AZURE_OPENAI_API_KEY
# - AZURE_OPENAI_ENDPOINT
# - AZURE_OPENAI_DEPLOYMENT_NAME
# - TAVILY_API_KEY
# - GOOGLE_API_KEY (for ADK)
# - Other configuration values
```
### 4. Install Dependencies
```bash
# Install dependencies using uv
uv sync --dev
# Or install without development dependencies
uv sync
```
## Running the System
### 1. Start LangConnect (Vector DB)
```bash
cd langconnect
make up # Start PostgreSQL + API server with Docker Compose
cd ..
```
### 2. Run the Entire System
```bash
# Grant execution permission (only needed once)
chmod +x scripts/run_all_agents.sh
# Start the system
./scripts/run_all_agents.sh
```
### 3. Individually Test LangGraph Agents
```bash
# Test with LangGraph Studio
./scripts/test_langgraph_agents.sh
```
### 4. Use the System
```bash
# CLI mode
python a2a_client/unified_research_agent.py
# Or make an API call
curl -X POST http://localhost:8000/research \
-H "Content-Type: application/json" \
-d '{"topic": "AI Trend Analysis", "depth": "comprehensive"}'
```
### 5. Run Individual A2A Servers
```bash
# 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 Endpoints
Each agent provides endpoints following the A2A protocol:
- **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
## Usage Examples
### Using the Python SDK
```python
from a2a_client import UnifiedResearchAgent, ResearchRequest
# Create an agent
agent = UnifiedResearchAgent()
# Create a research request
request = ResearchRequest(
topic="Comparative Analysis of Python Web Frameworks",
depth="comprehensive",
output_format="markdown"
)
# Conduct research
result = await agent.conduct_research(request)
# Print the result
print(result.report)
```
### Using the REST API
```bash
curl -X POST http://localhost:8000/research \
-H "Content-Type: application/json" \
-d '{
"topic": "Comparative Analysis of Python Web Frameworks",
"depth": "comprehensive"
}'
```
### Google ADK Web UI
```bash
# Start the ADK web UI
adk web a2a_client/
```
## Development Guide
### Project Structure
```
ttimes_guide_coding/
├── agents/ # LangGraph agents
│ ├── agent/ # Agent implementations
│ ├── a2a_servers/ # A2A server wrappers
│ ├── base/ # Base classes
│ └── tools/ # MCP clients
├── all-search-mcp/ # MCP server
├── a2a_client/ # Google ADK client
├── langconnect/ # Vector DB API
├── docker/ # Docker configurations
├── scripts/ # Execution scripts
└── docs/ # Reference documents
```
### Adding a New LangGraph Agent
1. Create a new agent file in the `/agents/agent/` directory
2. Inherit from the `BaseAgent` class and implement nodes/edges
3. Add a graph builder function in `/agents/graph_builders.py`
4. Register the agent in `langgraph.json`
5. Implement an A2A server wrapper (optional)
### Adding MCP Tools
1. Add a new tool function in `/all-search-mcp/server.py`
2. Define the tool with the `@mcp.tool()` decorator
3. Use it in agents through the MCP client
---
## MCP Server Development Guide
### 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:
```text
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 Development Guide
### Reference
[LangChain](https://python.langchain.com/llms.txt)
[LangConnect-Client](https://github.com/teddynote-lab/LangConnect-Client)
[LangGraph](https://langchain-ai.github.io/langgraph/llms-full.txt)
[LangChain-MCP-Adapter(client)](https://langchain-ai.github.io/langgraph/reference/mcp/)
[ModelContextProtocol](https://modelcontextprotocol.io/llms-full.txt)
[MCP-Python-SDK](https://github.com/modelcontextprotocol/python-sdk)
[FastMCP](https://github.com/jlowin/fastmcp)
[FastMCP-llms.txt](https://gofastmcp.com/llms-full.txt)
[A2A-SDK](https://github.com/a2aproject/a2a-python)
[A2A-Directory](https://github.com/sing1ee/a2a-directory)
### Cursor Tips
[REPOMIX](https://repomix.com/)
[CURSOR-Rules](https://docs.cursor.com/context/rules)
[CURSOR-RIPER-Framework](https://github.com/johnpeterman72/CursorRIPER.sigma)
