写在前面

最近在构建一个智能客服系统时，我遇到了一个经典问题：如何让AI Agent既能理解用户意图，又能调用外部工具获取实时信息？经过一段时间的摸索，我设计了一个轻量级的客服Agent框架。今天就把这个项目的核心代码和设计思路分享给大家。

先看一张整体架构图，感受一下这个Agent的工作流程：

一、项目结构解析

先看看我们的项目文件结构：

customer-service-agent/
├── main.py              # 主入口程序
├── agent.py             # Agent核心逻辑
├── op_llm_client.py    # Ollama客户端封装
├── config.json          # 配置文件
├── .env                 # 环境变量
└── tools.py             # 工具函数（示例）

二、核心代码深度解读

1. 配置管理模块

from __future__ import annotations
import json
from pathlib import Path
from typing import Any

ROOT = Path(__file__).resolve().parent

def load_config() -> dict[str, Any]:
    with (ROOT / "config.json").open(encoding="utf-8") as file:
        return json.load(config)

设计思路：使用from __future__ import annotations启用延迟注解评估，这在处理类型提示时能避免循环引用问题。配置管理独立成函数，方便后续扩展支持多种配置源。

2. 多Provider客户端工厂

python

def get_client(config: dict[str, Any]) -> tuple[Any, dict[str, Any]]:
    openai_config = config.get("openai", {})
    ollama_config = config.get("ollama", {})
    
    if openai_config.get("use_model", False):
        return (
            OpenAI(
                api_key=os.environ.get("API_KEY"),
                base_url=openai_config["base_url"],
            ),
            {
                "provider": "openai",
                "model_name": openai_config["model_name"],
                "temperature": openai_config.get("temperature", 0.2),
                "max_iterations": openai_config.get("max_iterations", 8),
            },
        )
    # ... Ollama类似

设计亮点：

• 工厂模式：根据配置动态创建不同的LLM客户端

• 统一接口：返回的配置字典包含了所有必要的运行时参数

• 降级方案：支持OpenAI和Ollama两种后端，本地开发可以用Ollama省钱

3. 对话循环与控制流

python

def main() -> None:
    load_dotenv(ROOT / ".env")
    config = load_config()
    client, agent_config = get_client(config)
    agent = CustomerServiceAgent(client, agent_config)

    while True:
        query = input("请输入您的问题（输入 exit 退出）：").strip()
        if query.lower() in {"exit", "quit", "退出"}:
            break
        if query:
            print(f"客服回复：{agent.ask(query)}")

这里采用了REPL模式（Read-Eval-Print Loop），这是构建交互式应用的经典模式。环境变量通过python-dotenv管理，敏感信息不会提交到代码仓库。

三、Agent核心架构设计

虽然agent.py的代码没有展示完整，但从调用方式agent.ask(query)可以推断出核心设计：

关键设计决策

1. 记忆管理：Agent内部维护消息列表，实现短期记忆

2. 工具调用：通过Function Calling机制实现能力扩展

3. 迭代控制：max_iterations防止无限循环

四、配置文件设计

json

{
  "openai": {
    "use_model": true,
    "base_url": "https://api.openai.com/v1",
    "model_name": "gpt-4",
    "temperature": 0.2,
    "max_iterations": 8
  },
  "ollama": {
    "use_model": false,
    "base_url": "http://127.0.0.1:11434",
    "model_name": "qwen2.5:7b",
    "temperature": 0.2,
    "max_iterations": 8
  }
}

配置哲学：

• 使用use_model开关，一次只能激活一个Provider

• temperature控制创造性，客服场景推荐0.1-0.3

• max_iterations平衡响应质量和性能

五、实战优化建议

1. 工具函数设计示例

python

# tools.py
def get_order_status(order_id: str) -> str:
    """获取订单状态"""
    # 实际项目中调用数据库或API
    return f"订单{order_id}状态：已发货"

def search_products(keyword: str) -> list:
    """搜索商品"""
    # 调用搜索引擎或数据库
    return [{"name": "智能客服系统", "price": 999}]

2. 错误处理增强

python

def ask(self, query: str) -> str:
    try:
        # ... 核心逻辑
    except Exception as e:
        logger.error(f"处理失败: {e}")
        return "抱歉，我暂时无法回答这个问题，请稍后再试。"

3. 性能优化

• 缓存机制：对重复查询使用Redis缓存

• 异步处理：对于耗时操作使用async/await

• 流式响应：对长回复使用流式输出提升体验

六、运行与测试

1. 安装依赖：

bash

pip install openai python-dotenv ollama

1. 配置环境：

bash

# .env文件
API_KEY=your_openai_api_key

1. 启动服务：

bash

python main.py

1. 测试对话：

text

请输入您的问题（输入 exit 退出）：我的订单什么时候到？
客服回复：您好，请提供您的订单号，我帮您查询...

七、进阶扩展方向

1. 多轮对话优化：引入对话状态机，处理复杂业务流程

2. 知识库增强：RAG检索增强生成，提供更准确的答案

3. 情感分析：识别用户情绪，提供更有温度的服务

4. 多模态支持：处理图片、语音等多种输入形式

5. 监控告警：接入日志系统，实时监控Agent运行状态

总结

这个轻量级客服Agent框架展示了如何用不到200行代码构建一个可扩展的AI应用。核心设计思想是：

• 配置驱动：通过配置文件控制行为

• 接口抽象：支持多种LLM Provider

• 工具扩展：通过Function Calling增强能力

• 记忆管理：维护对话上下文

在实际项目中，你可以基于这个框架快速搭建定制化的智能客服系统。记得根据业务需求调整max_iterations和temperature参数，在响应质量和速度之间找到最佳平衡点。

---

如果觉得本文对你有帮助，欢迎点赞收藏！有疑问可以在评论区交流，我会尽力解答。