apunkt/plano
1
0
Fork 0
mirror of https://github.com/katanemo/plano.git synced 2026-06-17 15:25:17 +02:00
Code Issues Projects Releases Packages Wiki Activity

update readme

Browse source
This commit is contained in:
Adil Hafeez 2025-12-16 12:14:16 -08:00
parent ab185b241a
commit 2abfa18bae
No known key found for this signature in database
GPG key ID: 9B18EF7691369645
1 changed files with 56 additions and 98 deletions
Download patch file Download diff file Expand all files Collapse all files

154
demos/use_cases/rag_agent/README.md
View file

@ -1,70 +1,56 @@
# RAG Agent with MCP Protocol
# RAG Agent Demo
A multi-agent RAG system using the Model Context Protocol (MCP) for agent communication.
A multi-agent RAG system demonstrating archgw's agent filter chain with MCP protocol.
## Architecture
This demo consists of three MCP agents:
1. **Query Rewriter** - Rewrites user queries for better retrieval
2. **Context Builder** - Retrieves relevant context from knowledge base
3. **Response Generator** - Generates final responses with context
This demo consists of three components:
1. **Query Rewriter** (MCP filter) - Rewrites user queries for better retrieval
2. **Context Builder** (MCP filter) - Retrieves relevant context from knowledge base
3. **RAG Agent** (REST) - Generates final responses based on augmented context
Each agent runs as an independent MCP server and exposes tools that can be called via the MCP protocol.
## Components
## MCP Tools
### Query Rewriter Agent
- **Tool**: `rewrite_query_with_archgw`
- **Description**: Rewrites user queries using LLM for better retrieval
- **Port**: 10500
### Context Builder Agent
- **Tool**: `chat_completions`
- **Description**: Augments queries with relevant context from knowledge base
### Query Rewriter Filter (MCP)
- **Port**: 10501
- **Tool**: `query_rewriter`
- Improves queries using LLM before retrieval
### Response Generator Agent
### Context Builder Filter (MCP)
- **Port**: 10502
- **Tool**: `context_builder`
- Augments queries with relevant passages from knowledge base
## Setup and Running
### RAG Agent (REST/OpenAI)
- **Port**: 10505
- **Endpoint**: `/v1/chat/completions`
- Generates responses using OpenAI-compatible API
### 1. Start archgw
## Quick Start
### 1. Start all agents
```bash
./start_agents.sh
```
This starts:
- Query Rewriter MCP server on port 10501
- Context Builder MCP server on port 10502
- RAG Agent REST server on port 10505
### 2. Start archgw
```bash
archgw up --foreground
```
### 2. Start Individual Agents
**Query Rewriter:**
### 3. Test the system
```bash
uv run python -m rag_agent \
--agent query_rewriter \
--host 0.0.0.0 \
--port 10500 \
--transport sse
```
**Context Builder:**
```bash
uv run python -m rag_agent \
--agent context_builder \
--host 0.0.0.0 \
--port 10501 \
--transport sse
```
**Response Generator:**
```bash
uv run python -m rag_agent \
--agent response_generator \
--host 0.0.0.0 \
--port 10502 \
--transport sse
```
### 3. Start All Agents at Once
```bash
./start_agents.sh
curl -X POST http://localhost:8001/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "What is the guaranteed uptime for TechCorp?"}]
}'
```
## Configuration
@ -81,56 +67,21 @@ agent_filters:
url: mcp://host.docker.internal:10501
tool: chat_completions
```
How It Works
### MCP Tool Invocation Patterns
1. User sends request to archgw listener on port 8001
2. Request passes through MCP filter chain:
- **Query Rewriter** rewrites the query for better retrieval
- **Context Builder** augments query with relevant knowledge base passages
3. Augmented request is forwarded to **RAG Agent** REST endpoint
4. RAG Agent generates final response using LLM
The config supports different ways to specify MCP tools:
## Configuration
**1. Separate tool field (recommended):**
```yaml
- id: query_rewriter
url: mcp://host.docker.internal:10500
tool: rewrite_query_with_archgw
```
**2. Tool in URL path:**
```yaml
- id: query_rewriter
url: mcp://host.docker.internal:10500/rewrite_query_with_archgw
```
**3. Tool as query parameter:**
```yaml
- id: query_rewriter
url: mcp://host.docker.internal:10500?tool=rewrite_query_with_archgw
```
## CLI Options
```bash
uv run python -m rag_agent --help
Options:
--transport TEXT Transport type: stdio or sse (default: sse)
--host TEXT Host to bind MCP server to (default: localhost)
--port INTEGER Port for MCP server (default: 10500)
--agent TEXT Agent name: query_rewriter, context_builder, or response_generator (required)
--name TEXT Custom MCP server name (optional)
```
## Environment Variables
```bash
# archgw LLM Gateway base URL (default: http://localhost:12000/v1)
export LLM_GATEWAY_ENDPOINT="http://localhost:12000/v1"
# OpenAI API Key for model providers
export OPENAI_API_KEY="your-key-here"
```
## Testing
See `sample_queries.md` for example queries to test the RAG system.
See `arch_config.yaml` for the complete filter chain setup. The MCP filters use default settings:
- `type: mcp` (default)
- `transport: streamable-http` (default)
- Tool name defaults to filter ID `sample_queries.md` for example queries to test the RAG system.
Example request:
```bash
@ -146,3 +97,10 @@ curl -X POST http://localhost:8001/v1/chat/completions \
]
}'
```
- `LLM_GATEWAY_ENDPOINT` - archgw endpoint (default: `http://localhost:12000/v1`)
- `OPENAI_API_KEY` - OpenAI API key for model providers
## Additional Resources
- See `sample_queries.md` for more example queries
- See `arch_config.yaml` for complete configuration details