From 2abfa18bae7f5001fdd3362872cc39ae50df2221 Mon Sep 17 00:00:00 2001 From: Adil Hafeez Date: Tue, 16 Dec 2025 12:14:16 -0800 Subject: [PATCH] update readme --- demos/use_cases/rag_agent/README.md | 154 ++++++++++------------------ 1 file changed, 56 insertions(+), 98 deletions(-) diff --git a/demos/use_cases/rag_agent/README.md b/demos/use_cases/rag_agent/README.md index 7b8b97b9..b3a54daf 100644 --- a/demos/use_cases/rag_agent/README.md +++ b/demos/use_cases/rag_agent/README.md @@ -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 \ No newline at end of file