diff --git a/sample_solutions/Docugen-Microagents/.env.example b/sample_solutions/Docugen-Microagents/.env.example
index c7d0c345..30e7da59 100644
--- a/sample_solutions/Docugen-Microagents/.env.example
+++ b/sample_solutions/Docugen-Microagents/.env.example
@@ -1,7 +1,3 @@
-# API Configuration
-BACKEND_PORT=8000
-FRONTEND_PORT=3000
-
# ==========================================
# Inference API Configuration
# ==========================================
diff --git a/sample_solutions/Docugen-Microagents/README.md b/sample_solutions/Docugen-Microagents/README.md
index 224eff7c..58b9fefc 100644
--- a/sample_solutions/Docugen-Microagents/README.md
+++ b/sample_solutions/Docugen-Microagents/README.md
@@ -264,7 +264,7 @@ This application supports multiple inference deployment patterns:
- The API key is the litellm_master_key value from the generated vault.yml file
**APISIX Gateway**: Provide your APISIX Gateway URL and authentication token
- - URL format: https://api.example.com/Llama-3.1-8B-Instruct
+ - URL format: https://api.example.com/Qwen3-4B-Instruct-2507
- Note: APISIX requires the model name in the URL path
- To generate the APISIX authentication token, use the [generate-token.sh](https://github.com/opea-project/Enterprise-Inference/blob/main/core/scripts/generate-token.sh) script
- The token is generated using Keycloak client credentials
diff --git a/sample_solutions/Docugen-Microagents/TROUBLESHOOTING.md b/sample_solutions/Docugen-Microagents/TROUBLESHOOTING.md
index 4e8ab5b9..8e5fb29c 100644
--- a/sample_solutions/Docugen-Microagents/TROUBLESHOOTING.md
+++ b/sample_solutions/Docugen-Microagents/TROUBLESHOOTING.md
@@ -59,19 +59,20 @@ netstat -ano | findstr :3000
## Configuration Errors
-### Missing GenAI Gateway API Key
+### Missing Inference API Token
-**Error:** `ValueError: GENAI_GATEWAY_API_KEY not configured`
+**Error:** `ValueError: INFERENCE_API_TOKEN not configured`
-**Cause:** API key not set in `.env` file.
+**Cause:** API token not set in `.env` file.
**Solution:**
```bash
# Copy environment template
-cp api/.env.example api/.env
+cp .env.example .env
-# Edit api/.env and add your API key
-GENAI_GATEWAY_API_KEY=your_actual_api_key_here
+# Edit .env and set your inference endpoint and token
+INFERENCE_API_ENDPOINT=https://api.example.com/Qwen3-4B-Instruct-2507
+INFERENCE_API_TOKEN=your-pre-generated-token-here
```
### Invalid GitHub Token
@@ -83,26 +84,24 @@ GENAI_GATEWAY_API_KEY=your_actual_api_key_here
**Solution:**
1. Generate a new Personal Access Token at https://github.com/settings/tokens
2. Select `repo` scope (full control of repositories)
-3. Update `GITHUB_TOKEN` in `api/.env`
+3. Update `GITHUB_TOKEN` in `.env`
4. Token format should be: `ghp_` followed by 36 alphanumeric characters
-### Authentication Mode Mismatch
+### Inference Endpoint Misconfigured
-**Error:** `KeyError: 'KEYCLOAK_CLIENT_SECRET'` or connection refused
+**Error:** `ConnectionError` or `401 Unauthorized` when calling the inference service
-**Cause:** AUTH_MODE set to keycloak but credentials not configured.
+**Cause:** `INFERENCE_API_ENDPOINT` or `INFERENCE_API_TOKEN` incorrect or not configured.
**Solution:**
```bash
-# For GenAI Gateway (recommended):
-AUTH_MODE=genai_gateway
-GENAI_GATEWAY_URL=https://your-gateway-url.com
-GENAI_GATEWAY_API_KEY=your_key_here
-
-# For Keycloak:
-AUTH_MODE=keycloak
-BASE_URL=https://your-inference-endpoint.com
-KEYCLOAK_CLIENT_SECRET=your_secret_here
+# GenAI Gateway (endpoint without model in path):
+INFERENCE_API_ENDPOINT=https://api.example.com
+INFERENCE_API_TOKEN=your-pre-generated-token-here
+
+# APISIX Gateway (model name included in the endpoint path):
+INFERENCE_API_ENDPOINT=https://api.example.com/Qwen3-4B-Instruct-2507
+INFERENCE_API_TOKEN=your-keycloak-generated-token-here
```
---
@@ -256,8 +255,8 @@ AGENT_TIMEOUT=600 # 10 minutes
- If much higher, repository may have very large files
3. **Network latency to LLM backend**
- - Ensure low latency network connection to GenAI Gateway
- - Check GENAI_GATEWAY_URL is accessible
+ - Ensure low latency network connection to the inference service
+ - Check INFERENCE_API_ENDPOINT is accessible
### High Token Usage
@@ -285,13 +284,13 @@ MAX_LINES_PER_FILE=300
**Solution:**
```bash
# Check backend logs for specific error
-docker-compose logs backend
+docker compose logs backend
# Common causes:
# 1. Missing .env file - solution above in Configuration Errors
# 2. Invalid Python dependencies - rebuild:
-docker-compose build --no-cache backend
-docker-compose up -d
+docker compose build --no-cache backend
+docker compose up -d
# 3. Port conflict - solution above in Installation Issues
```
@@ -303,8 +302,8 @@ docker-compose up -d
**Solution:**
```bash
# Rebuild frontend with clean cache
-docker-compose build --no-cache frontend
-docker-compose up -d frontend
+docker compose build --no-cache frontend
+docker compose up -d frontend
# Verify Node.js version in Dockerfile is compatible (16+)
```
@@ -332,33 +331,33 @@ MAX_LINES_PER_FILE=300
**Solution:**
```bash
# Verify both containers are running
-docker-compose ps
+docker compose ps
# Check backend is accessible
-curl http://localhost:5001/api/health
+curl http://localhost:5001/health
# Verify CORS_ORIGINS in api/.env includes frontend URL
CORS_ORIGINS=["http://localhost:3000"]
# Restart services
-docker-compose restart
+docker compose restart
```
---
## Network and API Errors
-### GenAI Gateway Connection Refused
+### Inference Service Connection Refused
**Error:** `ConnectionRefusedError: [Errno 111] Connection refused`
-**Cause:** GenAI Gateway URL incorrect or service unavailable.
+**Cause:** Inference endpoint URL incorrect or service unavailable.
**Solution:**
```bash
-# Verify GENAI_GATEWAY_URL is correct in api/.env
+# Verify INFERENCE_API_ENDPOINT is correct in .env
# Test connectivity:
-curl https://your-gateway-url.com/health
+curl https://api.example.com/health
# Check firewall/proxy settings allow outbound HTTPS
```
@@ -418,10 +417,10 @@ To get more detailed logs for debugging:
LOG_LEVEL=DEBUG
# Restart backend
-docker-compose restart backend
+docker compose restart backend
# View detailed logs
-docker-compose logs -f backend
+docker compose logs -f backend
```
### Check Agent Execution Metrics
@@ -457,7 +456,7 @@ If cloned repositories aren't cleaned up automatically:
rm -rf api/tmp/repos/*
# Or within Docker:
-docker-compose exec backend rm -rf /app/tmp/repos/*
+docker compose exec backend rm -rf /app/tmp/repos/*
```
### Reset Application State
@@ -466,14 +465,14 @@ To completely reset the application:
```bash
# Stop and remove containers
-docker-compose down -v
+docker compose down -v
# Remove temporary files
rm -rf api/tmp/*
# Rebuild and restart
-docker-compose build --no-cache
-docker-compose up -d
+docker compose build --no-cache
+docker compose up -d
```
---
@@ -482,9 +481,9 @@ docker-compose up -d
If you continue to experience issues:
-1. **Check Logs:** Review backend logs with `docker-compose logs backend -f`
+1. **Check Logs:** Review backend logs with `docker compose logs backend -f`
2. **Verify Configuration:** Ensure all required environment variables are set in `api/.env`
-3. **Test Connectivity:** Verify network access to GenAI Gateway and GitHub
+3. **Test Connectivity:** Verify network access to the inference service and GitHub
4. **Metrics Analysis:** Check workflow metrics for anomalies (token usage, duration, failed agents)
5. **Report Issues:** If the problem persists, collect:
- Error messages from logs
diff --git a/sample_solutions/Docugen-Microagents/docs/GENERIC_USAGE.md b/sample_solutions/Docugen-Microagents/docs/GENERIC_USAGE.md
index 58c59403..df7194ab 100644
--- a/sample_solutions/Docugen-Microagents/docs/GENERIC_USAGE.md
+++ b/sample_solutions/Docugen-Microagents/docs/GENERIC_USAGE.md
@@ -112,7 +112,7 @@ graph TB
end
subgraph "External Services"
- LLM[LLM Provider
Qwen3-4B via GenAI Gateway or Keycloak]
+ LLM[LLM Provider
Qwen3-4B via GenAI Gateway or APISIX]
GITHUB[GitHub
Public/private repos]
end
@@ -249,22 +249,20 @@ Each micro-agent operates autonomously with access to repository tools:
**LLM API Configuration** (required)
-Choose one authentication mode:
+Set your inference endpoint and token. Two gateway patterns are supported:
-**Option 1: GenAI Gateway (Recommended)**
+**Option 1: GenAI Gateway**
```bash
-AUTH_MODE=genai_gateway
-GENAI_GATEWAY_URL=https://your-gateway-url.com
-GENAI_GATEWAY_API_KEY=your-api-key
+# Endpoint without the model name in the path
+INFERENCE_API_ENDPOINT=https://api.example.com
+INFERENCE_API_TOKEN=your-pre-generated-token-here
```
-**Option 2: Keycloak (Enterprise)**
+**Option 2: APISIX Gateway**
```bash
-AUTH_MODE=keycloak
-BASE_URL=https://your-inference-endpoint.company.com
-KEYCLOAK_REALM=master
-KEYCLOAK_CLIENT_ID=api
-KEYCLOAK_CLIENT_SECRET=your-client-secret
+# Model name is included in the endpoint path
+INFERENCE_API_ENDPOINT=https://api.example.com/Qwen3-4B-Instruct-2507
+INFERENCE_API_TOKEN=your-keycloak-generated-token-here
```
**GitHub Personal Access Token** (optional, for private repos and PR creation)
@@ -290,21 +288,17 @@ The target repository must meet these criteria:
**Step 1:** Configure environment
-Create `api/.env`:
+Create `.env`:
```bash
# ==========================================
-# Authentication Configuration
+# Inference API Configuration
# ==========================================
-AUTH_MODE=genai_gateway
-GENAI_GATEWAY_URL=https://your-gateway-url.com
-GENAI_GATEWAY_API_KEY=your-api-key
+INFERENCE_API_ENDPOINT=https://api.example.com
+INFERENCE_API_TOKEN=your-pre-generated-token-here
-# OR for enterprise Keycloak authentication:
-# AUTH_MODE=keycloak
-# BASE_URL=https://your-inference-endpoint.company.com
-# KEYCLOAK_REALM=master
-# KEYCLOAK_CLIENT_ID=api
-# KEYCLOAK_CLIENT_SECRET=your-client-secret
+# OR for APISIX Gateway (model name included in the endpoint path):
+# INFERENCE_API_ENDPOINT=https://api.example.com/Qwen3-4B-Instruct-2507
+# INFERENCE_API_TOKEN=your-keycloak-generated-token-here
# ==========================================
# Micro-Agent Model Configuration
@@ -355,21 +349,21 @@ CORS_ORIGINS=["http://localhost:3000", "http://localhost:3001", "http://localhos
```bash
cd Docugen-Microagents
-docker-compose up -d
+docker compose up -d
```
**Step 3:** Verify deployment
```bash
# Check container status
-docker-compose ps
+docker compose ps
# Expected output:
-# docugen-backend Up (healthy)
-# docugen-frontend Up (healthy)
+# Docugen-Microagents-backend Up (healthy)
+# Docugen-Microagents-frontend Up (healthy)
# View logs
-docker-compose logs -f
+docker compose logs -f
# Access application
# Frontend: http://localhost:3000
@@ -868,7 +862,7 @@ curl -I https://github.com/owner/repo
- Regenerate token if expired
3. Restart backend to load new token:
```bash
- docker-compose restart backend
+ docker compose restart backend
```
### Micro-Agent Failures
@@ -878,7 +872,7 @@ curl -I https://github.com/owner/repo
**Diagnosis:**
```bash
# Check backend logs for agent-specific errors
-docker-compose logs backend | grep -i "agent.*error"
+docker compose logs backend | grep -i "agent.*error"
# Look for:
# - "Failed to parse JSON from agent output"
@@ -895,7 +889,7 @@ docker-compose logs backend | grep -i "agent.*error"
2. **LLM API errors:**
- Verify LLM endpoint is accessible
- - Check API key is valid (GENAI_GATEWAY_API_KEY or KEYCLOAK_CLIENT_SECRET)
+ - Check the token is valid (INFERENCE_API_TOKEN)
- Verify model names match available models
3. **Timeout errors:**
@@ -911,7 +905,7 @@ docker-compose logs backend | grep -i "agent.*error"
**View failed agents:**
```bash
# Check state.failed_agents in logs
-docker-compose logs backend | grep "failed_agents"
+docker compose logs backend | grep "failed_agents"
```
### Log Streaming Issues
@@ -945,13 +939,13 @@ PYTHONUNBUFFERED=1 python server.py
Verify Docker CLI installation in backend:
```bash
-docker-compose exec backend which docker
+docker compose exec backend which docker
# Should return: /usr/bin/docker
```
If not installed, rebuild backend:
```bash
-docker-compose up -d --build backend
+docker compose up -d --build backend
```
### Monorepo Project Detection
@@ -961,7 +955,7 @@ docker-compose up -d --build backend
**Diagnosis:**
```bash
# Check for package manager files
-docker-compose exec backend ls -la ./tmp/repos/*/
+docker compose exec backend ls -la ./tmp/repos/*/
# Look for:
# - package.json (Node.js)
@@ -982,7 +976,7 @@ docker-compose exec backend ls -la ./tmp/repos/*/
**Diagnosis:**
```bash
# Check container resource usage
-docker stats docugen-backend
+docker stats Docugen-Microagents-backend
```
**Resolution:**
@@ -1008,7 +1002,7 @@ docker stats docugen-backend
4. Check agent metrics for expensive agents:
```bash
- docker-compose logs backend | grep "agent_metrics"
+ docker compose logs backend | grep "agent_metrics"
```
### Context Window Exceeded
@@ -1018,7 +1012,7 @@ docker stats docugen-backend
**Diagnosis:**
```bash
# Check blast_radius_report in logs
-docker-compose logs backend | grep "blast_radius"
+docker compose logs backend | grep "blast_radius"
# Look for total_tokens_used exceeding 8000 (Qwen3-4B context window)
```
@@ -1049,7 +1043,7 @@ docker-compose logs backend | grep "blast_radius"
**Diagnosis:**
```bash
# Check QA validation results
-docker-compose logs backend | grep -A 20 "qa_validation_result"
+docker compose logs backend | grep -A 20 "qa_validation_result"
# Review feedback in logs:
# - Missing sections
@@ -1085,7 +1079,7 @@ docker-compose logs backend | grep -A 20 "qa_validation_result"
curl http://localhost:5001/health
# Check logs
-docker-compose logs backend
+docker compose logs backend
```
**Resolution:**
@@ -1097,12 +1091,12 @@ docker-compose logs backend
2. Check if services are running:
```bash
- docker-compose ps
+ docker compose ps
```
3. Restart services:
```bash
- docker-compose restart
+ docker compose restart
```
---
@@ -1117,11 +1111,10 @@ docker-compose logs backend
cp .env .env.example
# Document each variable with inline comments
-AUTH_MODE=genai_gateway # Required: Authentication mode
-GENAI_GATEWAY_URL=https://your-gateway.com # Required: GenAI Gateway URL
-GENAI_GATEWAY_API_KEY=your-key-here # Required: GenAI Gateway API key
-DATABASE_URL=postgresql://... # Required: PostgreSQL connection string
-REDIS_URL=redis://... # Optional: Redis for caching
+INFERENCE_API_ENDPOINT=https://api.example.com # Required: Inference service URL
+INFERENCE_API_TOKEN=your-token-here # Required: Inference service token
+DATABASE_URL=postgresql://... # Required: PostgreSQL connection string
+REDIS_URL=redis://... # Optional: Redis for caching
```
**Write Clear README Sections**
@@ -1254,13 +1247,12 @@ jobs:
- name: Run DocuGen Micro-Agents
env:
- GENAI_GATEWAY_URL: ${{ secrets.GENAI_GATEWAY_URL }}
- GENAI_GATEWAY_API_KEY: ${{ secrets.GENAI_GATEWAY_API_KEY }}
+ INFERENCE_API_ENDPOINT: ${{ secrets.INFERENCE_API_ENDPOINT }}
+ INFERENCE_API_TOKEN: ${{ secrets.INFERENCE_API_TOKEN }}
run: |
docker run -v $(pwd):/repo \
- -e AUTH_MODE=genai_gateway \
- -e GENAI_GATEWAY_URL=$GENAI_GATEWAY_URL \
- -e GENAI_GATEWAY_API_KEY=$GENAI_GATEWAY_API_KEY \
+ -e INFERENCE_API_ENDPOINT=$INFERENCE_API_ENDPOINT \
+ -e INFERENCE_API_TOKEN=$INFERENCE_API_TOKEN \
Docugen-Microagents:latest \
/repo
@@ -1372,7 +1364,8 @@ See **CUSTOMIZATION.md** for detailed customization guides:
See **api/.env.example** for complete list with descriptions.
**Key variables:**
-- `AUTH_MODE` - Authentication mode (genai_gateway | keycloak)
+- `INFERENCE_API_ENDPOINT` - Inference service URL (model name in path for APISIX)
+- `INFERENCE_API_TOKEN` - Inference service authentication token
- `MAX_LINES_PER_FILE` - File sampling budget (default 500)
- `AGENT_TIMEOUT` - Agent execution timeout in seconds (default 300)
- `AGENT_TEMPERATURE` - Model temperature 0.0-1.0 (default 0.7)
@@ -1391,7 +1384,7 @@ See **api/.env.example** for complete list with descriptions.
**Accessing metrics:**
```bash
# View in logs
-docker-compose logs backend | grep "agent_metrics"
+docker compose logs backend | grep "agent_metrics"
# Or via API
curl http://localhost:5001/api/metrics/{job_id}