AI导哈

AI销售代理

一个基于Model Context Protocol (MCP)的AI销售代理，通过WhatsApp或Web Standalone进行交互，支持产品搜索、购物车管理和库存查询。

  • by Kyriokes
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Kyriokes/Laburen-challenge

使用说明

Laburen挑战赛-人工智能销售代理（MCP+D1）

🎯 挑战的目标

该项目的目的是证明 对话式销售代理的设计与实现 通过 模型上下文协议（MCP）. 优先考虑了一个解耦且富有成效的架构，构建了一个具有真实状态持久性的自己的后端（REST API），能够自主处理复杂的业务流（搜索、购物车、库存）。

📱 WhatsApp频道（范围和限制）

该代理的设计和结构是为了在 WhatsApp.

  • 理想整合：WhatsApp->Twilio->Chatwoot->Laburen代理->MCP后端。
  • 当前状态（演示）：由于集成（Twilio）的运营成本和批准时间，功能演示是通过 Web独立 的Laburens。
  • 文件：在实际生产环境中激活WhatsApp频道的完整指南详细介绍在 docs/deployment_guide.md.

📐 概念阶段·人工智能代理设计

本节描述了为代理自主处理销售而设计的交互逻辑。

1.互动流程图

下图说明了代理如何协调工具以满足用户的意图，从探索到购物车管理。

sequenceDiagram
    participant U as Usuario
    participant A as Agente IA
    participant API as MCP Backend
    participant DB as D1 Database

    Note over U, A: Fase 1: Exploración
    U->>A: "Busco pantalones deportivos"
    A->>API: POST /products/list { "search": "pantalón deportivo" }
    API->>DB: SELECT * FROM products...
    DB-->>API: [ID: 5, ID: 12...]
    API-->>A: Lista de productos
    A-->>U: Muestra opciones con IDs y precios

    Note over U, A: Fase 2: Gestión de Carrito
    U->>A: "Quiero 2 unidades del ID 5"
    alt Carrito Nuevo
        A->>API: POST /cart { }
        API-->>A: { "cartId": 101 }
    end
    A->>API: POST /cart/add { "cartId": 101, "productId": 5, "qty": 2 }
    API->>DB: INSERT INTO cart_items...
    DB-->>API: OK
    API-->>A: Success
    A-->>U: "Agregado. ¿Algo más?"

    Note over U, A: Fase 3: Edición (Opcional)
    U->>A: "Mejor solo quiero 1"
    A->>API: POST /cart/update { "cartId": 101, "productId": 5, "qty": 1 }
    API-->>A: Updated
    A-->>U: "Listo, actualicé tu carrito."

2.端点定义

是 行动 该代理可以与系统交互。

不重要：MCP从不返回面向最终用户的文本。所有答案都是结构化的JSON，用于独家消费和代理推理。

端点 方法 描述 预期正文（JSON）
/products/list Post 在目录中搜索产品。 { "search": "keyword" }
/cart Post 初始化新的购买会话。 {}
/cart/add post 将项目添加到活动购物车中。 { "cartId": 1, "productId": 5, "qty": 2 }
/cart/get POST 获取购物车的当前状态和总数。 { "cartId": 1 }
/cart/update post 修改数量或删除（如果数量=0）。 { "cartId": 1, "productId": 5, "qty": 1 }

🚀 建筑

  • 运行时：Cloudflare Workers（无服务器）- 低延迟和即时可扩展性。
  • 数据库Cloudflare D1（分布式SQLite） 边缘轻快的坚持。
  • API设计：“代理优先”（仅限JSON/POST）- 优化用于LLM函数调用。
  • 语言：TypeScript- 类型安全性和可维护性。

📂 项目结构

/src
  /controllers  -> Lógica de negocio pura (SQL queries, validaciones), sin conocimiento del agente.
  /routes       -> Capa de contrato MCP (adaptadores HTTP para las Tools).
  index.ts      -> Entry point y Router principal.
/docs
  design.md          -> Diagramas de flujo y especificación técnica detallada.
  agent_config.md    -> System Prompt y JSON Schemas listos para copiar a Laburen.
  deployment_guide.md -> Guía paso a paso para integración (Twilio, Chatwoot, Deploy).
/scripts
  convert_xlsx_to_sql.js -> Utilidad ETL para importar productos desde Excel.

🛠️ 安装和本地使用

  1. 安装依赖项:

    npm install

  2. 启动本地服务器:

    npm run dev

    API将在 http://localhost:8787.

  3. Probar端点: 查看JSON示例 docs/design.md.

☁️ 生产部署

  1. 登录Cloudflare:
    npx wrangler login
  2. 初始化数据库（仅第一次）:
    npx wrangler d1 execute shop_db --remote --file=./schema.sql
npx wrangler d1 execute shop_db --remote --file=./seed_products.sql
  3. 派遣工人:
    npm run deploy

🤖 配置代理

要将此后端与人工智能连接：

  1. 复制部署的工作人员的URL。
  2. 美国 JSON模式 定义于 docs/agent_config.md 在Laburen中配置工具。
  3. 粘贴 系统提示 在模型配置中建议。

完成⚡和typescript。

相关 MCP