A2a Client Server Agent Router

⚠️ POC免责声明：这是一个概念验证（POC）实现。请不要评估此代码的生产级代码结构、模块化或最佳实践。本项目仅用于教育和示范目的。

A2A代理编排系统

目录

• 架构概述
• 组件和端口
• 先决条件
• 安装说明
• 启动代理服务器
• 外接WebSocket和前端
• 代理卡发现

一个多代理编排系统，可以智能地将用户查询路由到专门的代理：

🗄️ PostgreSQL数据库代理：使用llm生成SQL查询并执行数据库操作

• 总销售额超过3700的前5名客户
• 给我看看最大的销售发生在2025年

Jira代理：通过MCP工具提供以Jira为中心的助手

• 获取门票，映射用户ID→ 电子邮件，通过工具创建约会
• 语义缓存：在调用LLM之前，检查Redis是否有类似问题的先前答案（嵌入/密钥匹配）；在未命中时，它会生成一个新的响应并将其存储。

Jira代理流（缓存并避免误报）

1. 检查缓存（RedisVL）以查找语义相似的用户问题。
2. 如果在缓存中没有找到类似的问题：查询代理以生成新的答案并将其存储。
3. 如果在缓存中发现类似的问题：使用相似性代理进行验证以确认匹配。

• 如果匹配：返回缓存结果（来自RedivL）。
• 如果不匹配：查询代理以生成新的答案并更新缓存。

编排代理：确定调用哪个专业代理的智能路由器

• 智能查询分析和路由
• 代理之间的A2A协议通信
• 统一响应处理

MCP服务器：通过HTTP MCP为Jira代理提供工具（Jira、天气、约会）

外墙代理：UI的WebSocket桥；编排和MCP的代理

前端：两个React UI

• ai聊天前端keycloak认证（带keycloak）

架构概述

User → Frontend (WebSocket) → Facade (8081) → Orchestration (10003) → [DB (10000) | Jira (10002)]
                                                             ↓
                                                       Formatted Response

通信协议

• 通过HTTP实现代理到代理（A2A）
• UI的WebSocket↔ 立面流媒体
• MCP over HTTP用于工具调用

组件和端口

• PostgreSQL数据库代理：10000
• Postgres服务器和架构文件位于 postgres-db-agent/db/
• Jira代理：10002
• 编排代理：10003
• 外观（WebSocket）：8081

- WebSocket端点：ws://localhost:8081/ai代理/ws/{client_id}

• MCP服务器（快速MCP）：8001(http://localhost:8001/mcp)
• 前端（UI）：3000

______________________________________________________________________

先决条件

• Python 3.10+
• PostgreSQL数据库（用于DB代理）
• 一个OpenAI API密钥
• redis服务器
• 密钥斗篷服务器

创建一个 .env 每个代理目录中的文件包含：

OPENAI_API_KEY=your_openai_api_key

______________________________________________________________________

安装说明

每个代理/facea/mcp都需要自己的虚拟环境和依赖关系。按顺序执行以下步骤：

必需.env键（快速参考）

• PostgreSQL数据库代理（10000）：

- OPENAI_API密钥 - postgres_url（例如，postgresql://user:pass@本地主机：5432/dbname）

• Jira代理（10002）：

- OPENAI_API密钥 - MCP_SERVER_URL（例如。，http://localhost:8001/mcp) - REDIS_ENABLED

2.PostgreSQL数据库代理设置（端口10000）

从 postgres-db-agent/ 文件夹：

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Create .env with mandatory keys
cat > .env  .env  .env << 'EOF'
OPENAI_API_KEY=your_openai_api_key

DB_AGENT_URL=http://localhost:10000
JIRA_AGENT_URL=http://localhost:10002
EOF

______________________________________________________________________

启动代理服务器

⚠️ 重要：按此确切顺序启动服务器，以确保正确的依赖关系：

1.启动MCP服务器（端口8001）

cd mcp/
source venv/bin/activate
python mcp_server.py

2.启动PostgreSQL数据库代理（端口10000）

cd postgres-db-agent/
source venv/bin/activate
python a2a_postgres_agent.py

初始化数据库架构（一次，在Postgres服务器运行后）：

# Assuming local Postgres with user 'admin', database 'ai'
# Adjust -U and -d if your credentials differ
psql -h localhost -U admin -d ai -f postgres-db-agent/db/postgres.ddl

# Verify tables
psql -h localhost -U admin -d ai -c "\dt"

3.启动Jira代理（端口10002）

首先启动Redis（语义缓存需要）。从内部 jira-agent/ 运行docker compose：

cd jira-agent/
docker compose up -d  # starts redis on port 6379 (password: redispass123)

确认已启动：

redis-cli -a redispass123 PING  # should return PONG

然后启动Jira代理：

cd jira-agent/
source venv/bin/activate
python a2a_jira_server.py

4.启动编排代理（端口10003）

cd orchestration-agent/
source venv/bin/activate
python orchestration_agent.py

5.启动立面（端口8081）

Facade托管WebSocket端点和Orchestration的代理http://localhost:10003.

cd facade-agent/
python3 -m venv venv
source venv/bin/activate
pip install -e .   
cd src/
uvicorn ai_app.app:app --host 0.0.0.0 --port 8081

______________________________________________________________________

前端（Keycloak认证-先安装Keycloak服务器）

自 ai-chat-frontend-keycloak-auth/:

npm install
npm start

Keycloak配置已在 ai-chat-frontend-keycloak-auth/src/auth/keycloak.js:

• 网址：http://localhost:8080/
• 领域：satishrealm
• 客户端ID:testclient

这两个ui都会自动为WebSocket生成一个client_id（keycloak auth-ui的keycloak访问令牌），并提供一个简单的聊天。

代理卡发现

每个代理通过代理卡公开其功能。要下载代理卡，请执行以下操作：

# PostgreSQL DB Agent  
curl -H "Authorization: Bearer your_token" \
  http://localhost:10000/.well-known/agent-card.json

# Orchestration Agent (10003)
curl -H "Authorization: Bearer your_token" \
  http://localhost:10003/.well-known/agent-card.json

# Jira Agent (10002)
curl -H "Authorization: Bearer your_token" \
  http://localhost:10002/.well-known/agent-card.json

或者只需在浏览器中访问：

• http://localhost:10000/.well-已知/代理卡.json
• http://localhost:10003/.well-已知/代理卡.json
• http://localhost:10002/.well-已知/代理卡.json

______________________________________________________________________