showcase (Theoadu)

GHTechCorp客户支持聊天机器人

一个由OpenAI GPT-4o-mini和模型上下文协议（MCP）支持的智能客户支持聊天机器人，用于产品查询、订单管理和客户服务自动化。

______________________________________________________________________

📋 目录

• 概述
• 截图
• 建筑
• 技术栈
• 特性
• 入门指南
• 项目结构
• 运作原理
• 反思
• 未来的增强功能
• 贡献

______________________________________________________________________

🎯 概述

这个项目是 概念验证客户支持聊天机器人 GHTechCorp是一家虚构的计算机产品公司。聊天机器人帮助客户：

• 产品发现：浏览、搜索并获取有关显示器、计算机、打印机和配件的详细信息
• 订单管理：检查订单状态，查看订单历史记录，并下新订单
• 客户验证：为敏感操作提供安全的基于PIN的身份验证
• 实时支持：具有上下文感知响应的对话式AI界面

该系统展示了 模型上下文协议（MCP） 随着 LangChain 和 OpenAI的GPT-4o-mini 创建一个工具增强的会话代理，可以访问外部API。

📸 截图

聊天界面

*主要的Gradio聊天界面，客户可以在其中与AI支持代理进行交互*

代理人在行动

*示例对话显示代理使用工具搜索产品并提供建议*

______________________________________________________________________

🏗️ 建筑

高级体系结构

graph TB
    User[👤 User] -->|Chat Interface| Gradio[Gradio Web UI]
    Gradio -->|User Message| ChatHandler[Chat Handler]
    ChatHandler -->|Initialize| Agent[LangChain Agent]
    Agent -->|Get Tools| MCP[MCP Client]
    MCP -->|HTTP Request| Server[MCP Server
AWS App Runner]
    Server -->|Tools List| MCP
    MCP -->|Tools| Agent
    Agent -->|Invoke with Tools| LLM[OpenAI GPT-4o-mini]
    LLM -->|Tool Calls| Agent
    Agent -->|Execute Tools| MCP
    MCP -->|API Calls| Server
    Server -->|Data| MCP
    MCP -->|Results| Agent
    Agent -->|Process| LLM
    LLM -->|Response| Agent
    Agent -->|Final Response| ChatHandler
    ChatHandler -->|Display| Gradio
    Gradio -->|Show Message| User
    
    style User fill:#e1f5ff
    style LLM fill:#fff4e1
    style Server fill:#ffe1f5
    style Agent fill:#e1ffe1

组件交互流程

sequenceDiagram
    participant U as User
    participant G as Gradio UI
    participant C as Chat Handler
    participant A as LangChain Agent
    participant M as MCP Client
    participant S as MCP Server
    participant O as OpenAI GPT-4o-mini

    U->>G: Enter message
    G->>C: chat(message, history)
    C->>M: get_tools()
    M->>S: HTTP GET /tools
    S-->>M: Return tools list
    M-->>C: Tools available
    C->>A: create_agent(model, tools, prompt)
    A->>O: Send message + tools + history
    O-->>A: Tool call request
    A->>M: Execute tool(params)
    M->>S: HTTP POST /tool_execution
    S-->>M: Tool result
    M-->>A: Return data
    A->>O: Continue with tool results
    O-->>A: Final response
    A-->>C: Response message
    C-->>G: Yield response
    G-->>U: Display message

系统架构组件

graph LR
    subgraph "Frontend Layer"
        UI[Gradio Interface]
    end
    
    subgraph "Application Layer"
        App[app.py]
        Prompt[System Prompt]
        Logger[Logger]
    end
    
    subgraph "Agent Layer"
        Agent[LangChain Agent]
        MCP[MCP Client
MultiServerMCPClient]
    end
    
    subgraph "LLM Layer"
        OpenAI[OpenAI GPT-4o-mini]
    end
    
    subgraph "External Services"
        MCPS[MCP Server
AWS App Runner
Products API]
    end
    
    UI --> App
    App --> Agent
    App --> Prompt
    App --> Logger
    Agent --> MCP
    Agent --> OpenAI
    MCP --> MCPS
    
    style UI fill:#4A90E2
    style Agent fill:#50C878
    style OpenAI fill:#F39C12
    style MCPS fill:#E74C3C

______________________________________________________________________

🛠️ 技术栈

核心技术

体系结构模式

• 基于Agent的体系结构：自主决策与工具选择
• 模型上下文协议（MCP）：将LLM连接到外部数据源的标准化协议
• 事件驱动UI：响应式聊天界面的异步/等待模式
• 提示工程：系统提示定义代理行为和功能

______________________________________________________________________

✨ 特性

核心能力

✅ 产品管理

• 列出具有可选类别筛选的产品
• 按关键字搜索产品
• 按SKU获取详细的产品信息

✅ 订单管理

• 按客户ID查看订单历史记录
• 检查订单状态和详细信息
• 通过验证创建新订单

✅ 客户验证

• 基于PIN的身份验证系统
• 安全的客户身份验证
• 受保护订单创建工作流

✅ 会话界面

• 自然语言理解
• 上下文感知响应
• 使用用户友好的消息处理错误
• 聊天历史记录支持

工具集成

代理可以通过MCP服务器访问以下工具。这些工具使聊天机器人能够与产品数据库、客户记录和订单管理系统进行交互。

产品工具

demo-list_products

• 描述：按类别或活动状态列出具有可选筛选器的产品
• 用例：浏览库存、检查库存或查找可用产品
• 参数:

- category （可选）：按产品类别筛选（例如，“显示器”、“计算机”、“打印机”） - is_active （可选）：按活动状态筛选（布尔值）

• 退货：包含基本信息的产品列表

demo-get_product

• 描述：使用SKU检索特定产品的详细信息
• 用例：获取价格、库存、描述和其他产品详细信息
• 参数:

- sku （必填）：产品SKU代码（例如“MON-0054”、“COM-0001”）

• 退货：完整的产品详细信息，包括定价、库存和规格

demo-search_products

• 描述：按名称或描述中的关键字搜索产品（不区分大小写，部分匹配）
• 用例：按功能或搜索词查找项目
• 参数:

- query （必填）：搜索关键字或短语

• 退货：匹配产品列表

客户工具

demo-get_customer

• 描述：使用客户ID（UUID）获取客户信息
• 用例：查找客户详细信息、收货地址或角色
• 参数:

- customer_id （必填）：客户的UUID

• 退货：客户资料，包括联系信息和运输详细信息

demo-verify_customer_pin

• 描述：使用电子邮件和4位PIN验证客户的身份
• 用例：在敏感操作之前对客户进行身份验证（创建订单之前需要）
• 参数:

- email （必填）：客户的电子邮件地址 - pin （必填）：4位PIN码

• 退货：如果身份验证成功，则显示客户详细信息，否则显示错误
• 安全说明：必须在之前致电 demo-create_order

订购工具

demo-list_orders

• 描述：列出订单，可选择按客户ID或状态筛选
• 用例：查看订单历史或跟踪待处理订单
• 参数:

- customer_id （可选）：UUID，用于按客户筛选订单 - status （可选）：订单状态（例如，“草稿”、“已提交”、“批准”、“完成”、“取消”）

• 退货：与筛选器匹配的订单列表

demo-get_order

• 描述：检索特定订单的完整详细信息，包括行项目
• 用例：检查订单内容或分析采购产品
• 参数:

- order_id （必填）：订单的UUID

• 退货：完整的订单详细信息，包括行项目、定价和状态

demo-create_order

• 描述：使用指定项目为客户创建新订单
• 用例：在客户验证后下新订单
• 参数:

- customer_id （必填）：客户的UUID - items （必填）：订单项数组，每个订单项包含： - sku：产品SKU代码 - quantity：项目数量 - unit_price：价格为字符串（例如“299.99”） - currency：货币代码（例如“USD”）

• 退货：已创建状态为“已提交”的订单
• 验证：自动检查库存可用性和客户有效性
• 安全说明：需要事先通过以下方式进行客户验证 demo-verify_customer_pin

______________________________________________________________________

🚀 入门指南

先决条件

• Python 3.13或更高版本
• OpenAI API密钥
• 互联网连接（用于MCP服务器访问）

安装

1. 克隆存储库

   git clone 
   cd showcase

1. 创建虚拟环境

   python3 -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

1. 安装依赖项

使用 uv （推荐）：

   uv sync

或使用 pip:

   pip install -r requirements.txt

1. 配置环境变量

   cp .env.example .env

编辑 .env 并添加您的OpenAI API密钥：

   OPENAI_API_KEY=sk-proj-xxxxx

运行应用程序

python app.py

或使用 uv:

uv run app.py

Gradio界面将启动并提供：

• 本地URL: http://127.0.0.1:7860
• 公共URL:可供外部访问的共享链接

______________________________________________________________________

📁 项目结构

showcase/
├── app.py                 # Main application entry point
├── prompt.py              # System prompt and agent instructions
├── logger.py              # Logging configuration
├── pyproject.toml         # Project metadata and dependencies
├── requirements.txt        # Pip requirements file
├── .env.example           # Environment variable template
├── .env                   # Environment variables (gitignored)
├── .gitignore             # Git ignore rules
└── README.md              # This file

关键文件

app.py

• 使用服务器配置初始化MCP客户端
• 创建Gradio聊天界面
• 通过代理调用处理异步聊天功能
• 错误处理和日志

prompt.py

• 全面的系统提示定义代理行为
• 工具使用指南
• 订单创建的安全协议
• 响应风格和限制

logger.py

• 简单的日志配置
• 开发调试级别

______________________________________________________________________

🔍 运作原理

1.初始化

应用程序启动时：

1. 环境变量从以下位置加载 .env
2. MCP客户端连接到AWS App Runner上的产品服务器
3. Gradio web界面已初始化

2.聊天流程

当用户发送消息时：

async def chat(message, history):
    # 1. Retrieve available tools from MCP server
    tools = await client.get_tools()
    
    # 2. Create LangChain agent with GPT-4o-mini
    agent = create_agent("gpt-4o-mini", tools, system_prompt=SYSTEM_PROMPT)
    
    # 3. Invoke agent with message and history
    result = await agent.ainvoke({
        "messages": history + [HumanMessage(content=message)]
    })
    
    # 4. Return the agent's response
    yield result["messages"][-1].content

3.代理人决策

代理人：

1. 从消息中分析用户意图
2. 确定要使用哪些工具（如果有的话）
3. 对MCP服务器进行工具调用
4. 处理结果并制定响应
5. 返回自然语言答案

4.MCP服务器集成

MCP客户端使用 HTTP传输 与远程服务器通信：

client = MultiServerMCPClient({
    "products": {
        "transport": "streamable_http",
        "url": "https://vipfapwm3x.us-east-1.awsapprunner.com/mcp"
    }
})

______________________________________________________________________

💭 反思

什么进展顺利✅

1. MCP集成：模型上下文协议与LangChain的集成无缝协作，为工具使用提供了清晰的抽象

1. 代理自主性：GPT-4o-mini在确定何时以及如何使用工具方面表现出强大的推理能力

1. Gradio用户界面Gradio提供的聊天界面简单而有效，只需要最少的代码

1. 系统提示设计：详细的系统提示有效地指导代理行为，包括安全协议和响应风格

1. 错误处理：基本错误处理可防止崩溃，并提供用户友好的错误消息

1. 异步架构：async/await模式支持响应式UI和高效的I/O操作

哪些方面可以改进⚠️

1. 错误处理:

- 通用错误消息不提供具体指导 - 瞬态故障没有重试逻辑 - MCP服务器连接错误可能更具描述性

1. 认证:

- 无会话管理或用户持久性 - PIN验证以纯文本形式进行 - 无速率限制或暴力保护

1. 测试:

- 无单元测试或集成测试 - 工具交互没有测试覆盖率 - 仅手动测试

1. 日志记录:

- 最少的日志记录实施 - 无结构化日志记录或日志聚合 - 生产中未捕获调试日志

1. 配置:

- MCP服务器URL是硬编码的 - 不支持多种环境 - 可配置性有限

1. 用户体验:

- 工具执行期间没有加载指示器 - 无对话导出功能 - 聊天记录有限（无持久性）

1. 可观测性:

- 无指标或监控 - 调试代理决策没有跟踪 - 未对工具使用情况进行分析

1. 可扩展性:

- 单线程异步实现 - 不缓存频繁访问的数据 - MCP客户端为每条消息重新创建连接

______________________________________________________________________

🔮 未来的增强功能

短期改善

1. 增强的错误处理

   # Add retry logic with exponential backoff
   # Provide specific error messages
   # Graceful degradation when tools are unavailable

1. 会话管理

- 使用cookie/JWT实现用户会话 - 将对话历史记录存储在数据库中 - 允许导出和共享对话

1. 测试套件

- 聊天处理程序的单元测试 - MCP客户端集成测试 - OpenAI API调用的模拟测试

1. 改进日志记录

   # Structured JSON logging
   # Request/response tracing
   # Performance metrics

中期特征

1. 多租户支持

- 支持多种公司配置 - 公司特定的品牌和提示 - 每个租户的独立数据访问

1. 高级分析

- 对话分析仪表板 - 工具使用统计 - 客户满意度指标 - 代理性能监控

1. 增强的安全性

- OAuth2身份验证 - 基于角色的访问控制（RBAC） - 加密数据传输 - 审计日志

1. 缓存层

   # Redis cache for product data
   # LRU cache for frequent queries
   # Reduce MCP server load

1. 流媒体响应

   # Token-by-token streaming
   # Real-time tool execution updates
   # Improved perceived performance

长期愿景

1. 多模式支持

- 产品问题图片上传 - 语音输入/输出 - 手册的PDF文档解析

1. 高级代理功能

- 多Agent协作 - 记忆和个性化 - 主动建议 - 情感分析

1. 一体化生态系统

- CRM集成（Salesforce、HubSpot） - 票务系统集成（Zendesk、Jira） - 电子邮件和短信通知 - 支付处理集成

1. 人类交接

- 升级到人类代理 - 无缝上下文传输 - 协作聊天模式

1. 部署选项

- Docker容器化 - Kubernetes编排 - CI/CD管道 - 多区域部署

1. 替代LLM支持

- 支持拟人克劳德 - 支持本地型号（Llama、Mistral） - 基于任务的模型选择 - 成本优化策略

______________________________________________________________________

🤝 贡献

欢迎投稿！以下是您可以提供帮助的方式：

1. 克隆该仓库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

开发设置

# Install development dependencies
pip install -e ".[dev]"

# Run linting
ruff check .

# Run formatting
black .

# Run tests
pytest

______________________________________________________________________

📝 许可证

该项目仅用于演示目的。根据需要修改和使用您自己的项目。

______________________________________________________________________

🙏 致谢

• 模型上下文协议（MCP）：提供将LLM连接到外部工具的标准化方法
• LangChain：用于优秀的代理编排框架
• 度：用于简单而强大的UI框架
• 开放人工智能：GPT-4o-mini令人印象深刻的推理能力

______________________________________________________________________

📧 联系

如有疑问或反馈，请在存储库中打开问题。

______________________________________________________________________

建于❤️ 使用Python、LangChain和OpenAI

展示