droideronline/pyconf-hyd-2026-trustworthy-llm-agents
GitHub: droideronline/pyconf-hyd-2026-trustworthy-llm-agents
基于LangGraph构建的多智能体客服系统演示项目，展示LLM应用的可观测性、评估与安全护栏最佳实践。
Stars: 0 | Forks: 0
# Support Swarm — PyConf Hyd 2026
基于 **LangGraph**、**LangChain** 和 **PostgreSQL + pgvector** 构建的多智能体客服系统。这是名为《LLM Agents 的可观测性、评估与安全护栏》工作坊的演示项目。
## 架构
```
User Query
│
▼
┌──────────┐
│ Router │ ← structured output intent detection (ProviderStrategy)
└──────────┘
│
├─ general ────────► ShopAssist (lookup_order, process_refund, send_email, search_knowledge_base)
├─ order_support ──► ShopAssist
├─ policy_inquiry ─► PolicyAdvisor (search_knowledge_base)
└─ escalation ─────► EscalationAgent (search_knowledge_base, send_email)
```
## 前置条件
- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (Python 包管理器)
- Docker & Docker Compose
- Node.js 20+ 和 [pnpm](https://pnpm.io/) (用于本地 UI 开发)
- 一个 OpenAI API 密钥 (或 Azure OpenAI 凭证)
## 快速开始
有两种方式运行此项目：**Docker Compose** (推荐) 或 **本地开发**。
### 选项 A: Docker Compose (推荐)
使用一条命令运行整个技术栈 (数据库、后端和 UI)。
#### 1. 配置环境
```
cp .env.example .env
```
编辑 `.env` 并设置您的 API 密钥：
```
OPENAI_API_KEY=sk-your-key-here
```
对于 Azure OpenAI，请设置 `LLM_PROVIDER=azure_openai` 并填写 Azure 相关字段。
#### 2. 启动所有服务
```
docker compose up --build
```
这将启动三个服务：
| Service | Port | Description |
| ------------ | ---- | ------------------------------------ |
| **db** | 5432 | PostgreSQL 16 + pgvector |
| **langgraph**| 2024 | LangGraph dev server (Python backend)|
| **ui** | 3000 | Agent Chat UI (Next.js frontend) |
#### 3. 初始化数据库
在另一个终端中执行：
```
docker compose exec langgraph uv run python -m support_swarm.db.seed
```
#### 4. 打开 UI
访问 **http://localhost:3000** 并开始聊天。
#### 常用命令
```
# 查看 logs
docker compose logs -f
# 查看特定 service 的 logs
docker compose logs -f langgraph
# 重启单个 service
docker compose restart langgraph
# 停止所有内容并移除 volumes
docker compose down -v
```
### 选项 B: 本地开发
#### 1. 克隆并安装依赖
```
git clone https://github.com/droideronline/pyconf-hyd-2026-trustworthy-llm-agents.git
cd pyconf-hyd-2026-trustworthy-llm-agents
uv sync
```
#### 2. 配置环境
```
cp .env.example .env
```
编辑 `.env` 并设置您的 API 密钥：
```
OPENAI_API_KEY=sk-your-key-here
```
对于 Azure OpenAI，请设置 `LLM_PROVIDER=azure_openai` 并填写 Azure 相关字段。
#### 3. 启动 PostgreSQL + pgvector
```
docker compose up -d db
```
#### 4. 初始化数据库
创建数据表并插入示例数据 (客户、订单、知识库文章)：
```
uv run python -m support_swarm.db.seed
```
#### 5. 为知识库生成 Embeddings
此步骤需要设置您的 `OPENAI_API_KEY`：
```
uv run python -m support_swarm.db.seed --embeddings
```
#### 6. 启动后端 (LangGraph dev server)
```
uv run langgraph dev --no-browser
```
服务将在 **http://localhost:2024** 启动。可通过以下方式验证：
```
curl http://localhost:2024/ok
# {"ok": true}
```
#### 7. 启动前端 (Agent Chat UI)
在新终端中执行：
```
cd agent-chat-ui
pnpm install
pnpm dev
```
UI 将在 **http://localhost:3000** 打开。
## 项目结构
```
├── support_swarm/
│ ├── config/ # Settings, YAML config loader
│ ├── db/
│ │ ├── models/ # SQLAlchemy ORM (Customer, Order, Refund, EmailLog, KnowledgeArticle)
│ │ ├── engine.py # DB engine + session management
│ │ └── seed.py # Seed data + embedding generation
│ ├── declarative/
│ │ ├── agents/ # YAML agent specs (router, shop_assist, policy_advisor, escalation_agent)
│ │ ├── models.py # AgentSpec Pydantic model
│ │ └── yaml_utils.py # YAML loader
│ ├── tools/
│ │ ├── registry.py # Tool registry with @register_tool decorator
│ │ ├── shop_assist_tools.py # lookup_order, process_refund, send_email
│ │ └── shared.py # search_knowledge_base (pgvector semantic search)
│ ├── enums.py # Agent name enums
│ ├── model_client.py # LLM + embedding client factory
│ └── workflow.py # LangGraph multi-agent workflow with structured routing
├── agent-chat-ui/ # LangChain Agent Chat UI (Next.js)
├── langgraph.json # LangGraph dev server config
├── settings.yaml # App config (env var driven)
├── docker/ # Dockerfiles for langgraph and UI services
├── docker-compose.yml # Full stack: PostgreSQL + LangGraph + Chat UI
└── pyproject.toml # Python dependencies (managed by uv)
```
## 种子数据
| Table | Records | Notes |
| ------------------ | ------- | --------------------------------------------------- |
| customers | 4 | Alice, Bob, Charlie, Eve |
| orders | 7 | ORD-1001 to ORD-1007 (various statuses and amounts) |
| knowledge_articles | 5 | Return, Refund, Shipping, Warranty, Escalation |
标签：Apex, API集成, Azure, ChatBot, CISA项目, DeepEval, DLL 劫持, Docker, GET参数, LangChain, LangGraph, LLMOps, OpenAI, OpenTelemetry, pgvector, PostgreSQL, PyRIT, Python, RAG, 人工智能, 全栈, 内存规避, 可观测性, 向量数据库, 多智能体系统, 大语言模型, 安全护栏, 安全防御评估, 客户支持, 工作流自动化, 意图识别, 无后门, 本体建模, 机器学习, 检索增强生成, 测试用例, 用户代理, 用户模式Hook绕过, 研讨会, 自动化攻击, 评估, 请求拦截, 路由分发, 轻量级, 逆向工具