智能体核心技术七大模块详解 - 添加OpenAI支持

千江明月

285人浏览 · 2026-03-16 21:40:15

千江明月 · 2026-03-16 21:40:15 发布

前面对从“对话助手”升级为“执行专家”的核心技术七大模块进行详解，用一个模拟的LLM，现在准备使用OpenAI支持。

要求为已有的智能体项目添加OpenAI支持。目前代码中使用了MockLLM作为模拟LLM，需要实现一个OpenAILLM类，使用OpenAI API进行推理。同时需要考虑配置API密钥、模型选择等。另外，需要更新reasoning.py中的decide方法，因为原有的MockLLM是简单的规则匹配，而实际OpenAI需要更合理的prompt工程。此外，需要更新requirements.txt加入openai。

我们需要提供详细的方案，并修改/添加相关文件。但注意，《智能体核心技术七大模块详解》原文中已经包含了完整的项目结构，我们需要在此基础上增加OpenAI支持。

下面在现有项目中集成OpenAI。

我们需要：

在agent/llm/下创建openai.py，实现OpenAILLM类，继承BaseLLM。
修改examples/task_execution.py，演示如何使用OpenAI LLM（可选，但为了完整性）。
更新requirements.txt添加openai。
需要对prompt进行优化，以适应OpenAI的格式。在reasoning.py中，构造的prompt可能已经足够，但为了更好的结果，需要调整。

另外，需要考虑API密钥的配置，可以通过环境变量OPENAI_API_KEY或传入参数。

《智能体核心技术七大模块详解》原文中已经很详细，但为了满足用户需求，我们需要在现有基础上扩展。我们给出一个补充说明，包括新增的文件和修改的内容。

最终输出包含：新的openai.py代码，更新后的reasoning.py（如果有必要修改），更新后的requirements.txt，以及修改后的示例代码。

注意：OpenAI API的调用需要处理错误、重试等，但我们保持简单。

我们也将提及如何设置API密钥。

下面开始编写。

集成 OpenAI 作为推理引擎

在原有智能体框架基础上，只需增加一个 OpenAILLM 类，并在创建 Agent 时传入该实例即可。以下详细说明实现步骤及代码修改。

1. 安装 OpenAI Python 包

在 requirements.txt 中添加：

openai>=1.0.0

2. 实现 OpenAILLM 类

新建文件 agent/llm/openai.py，内容如下：

import os
from openai import OpenAI
from .base import BaseLLM

class OpenAILLM(BaseLLM):
    """使用 OpenAI API 的 LLM 封装"""

    def __init__(self, model: str = "gpt-3.5-turbo", api_key: str = None, base_url: str = None):
        """
        初始化 OpenAI 客户端
        :param model: 模型名称，如 "gpt-3.5-turbo", "gpt-4"
        :param api_key: API Key，默认从环境变量 OPENAI_API_KEY 读取
        :param base_url: 自定义 API 地址（可用于代理或兼容 OpenAI 格式的服务）
        """
        self.model = model
        # 优先使用传入的 api_key，否则从环境变量获取
        api_key = api_key or os.getenv("OPENAI_API_KEY")
        if not api_key:
            raise ValueError("OpenAI API key is required. Set OPENAI_API_KEY environment variable or pass api_key.")
        self.client = OpenAI(api_key=api_key, base_url=base_url)

    def generate(self, prompt: str) -> str:
        """
        调用 OpenAI ChatCompletion 生成回复
        """
        try:
            response = self.client.chat.completions.create(
                model=self.model,
                messages=[{"role": "user", "content": prompt}],
                temperature=0.2,  # 降低随机性，更适合工具调用
                max_tokens=500
            )
            return response.choices[0].message.content.strip()
        except Exception as e:
            # 简单错误处理，实际可重试或返回错误信息
            return f"OpenAI API 调用失败: {str(e)}"

3. 调整推理模块的 Prompt

为了使 OpenAI 更好地理解 ReAct 格式，可以优化 reasoning.py 中的 prompt，明确指定输出格式并加入示例（few-shot）。以下为修改后的 decide 方法（仅展示修改部分，其他不变）：

# agent/core/reasoning.py 中的 decide 方法

def decide(self, state_description: str, memory: List[Message], tools: Dict) -> Action:
    # 构建工具描述
    tools_desc = "\n".join([f"- {t.name}: {t.description}" for t in tools.values()])
    memory_text = "\n".join([f"{m.role}: {m.content}" for m in memory[-5:]])

    # 加入 few-shot 示例，帮助模型理解格式
    examples = """
用户: 计算 25 的平方根
助手:
Thought: 用户需要计算平方根，我可以使用计算器工具。
Action: calculator
Action Input: {"expression": "sqrt(25)"}

用户: 北京天气怎么样？
助手:
Thought: 用户查询北京天气，我需要调用天气工具。
Action: weather
Action Input: {"city": "北京"}

用户: 发送邮件给李四说项目延期
助手:
Thought: 需要先获取李四的邮箱地址，再发送邮件。
Action: email
Action Input: {"action": "get_email", "name": "李四"}

(获取到邮箱后，再次思考)
助手:
Thought: 现在有了邮箱地址，可以发送邮件了。
Action: email
Action Input: {"action": "send", "to": "lisi@example.com", "content": "项目延期"}
"""

    prompt = f"""你是一个智能助手，可以调用工具来帮助用户。请严格按照 ReAct 格式思考并输出。

可用工具：
{tools_desc}

对话历史（最近几条）：
{memory_text}

当前状态：{state_description}

示例：
{examples}

请根据以上信息，决定下一步动作。只输出以下格式之一，不要额外内容：

Thought: 你的思考过程
Action: 工具名称
Action Input: JSON格式的输入参数

或

Final Answer: 最终答案

现在开始：
"""
    response = self.llm.generate(prompt).strip()
    return self._parse_response(response)

4. 修改示例以使用 OpenAI

更新 examples/task_execution.py，使用 OpenAILLM 替换 MockLLM：

import sys
sys.path.append("..")

from agent.core.agent import Agent
from agent.llm.openai import OpenAILLM   # 导入 OpenAI LLM
from agent.tools.calculator import CalculatorTool
from agent.tools.weather import WeatherTool
from agent.tools.email import EmailTool

def main():
    # 使用 OpenAI LLM（需设置环境变量 OPENAI_API_KEY）
    llm = OpenAILLM(model="gpt-3.5-turbo")  # 可选指定模型
    agent = Agent(llm)
    agent.register_tool(CalculatorTool())
    agent.register_tool(WeatherTool())
    agent.register_tool(EmailTool())

    # 任务1：计算
    print("用户：计算 3+5*2")
    response = agent.run("计算 3+5*2")
    print(f"助手：{response}\n")

    # 任务2：天气查询
    print("用户：上海天气怎么样？")
    response = agent.run("上海天气怎么样？")
    print(f"助手：{response}\n")

    # 任务3：发送邮件
    print("用户：发送邮件给张三说下午开会")
    response = agent.run("发送邮件给张三说下午开会")
    print(f"助手：{response}\n")

if __name__ == "__main__":
    main()

5. 环境变量设置

运行前需设置 OpenAI API 密钥，例如在命令行：

export OPENAI_API_KEY="sk-xxxxxx"

或在代码中直接传入 api_key 参数。

6. 注意事项

模型选择：推荐使用 gpt-3.5-turbo 或 gpt-4，后者更智能但成本较高。
Prompt 优化：可根据实际效果调整 few-shot 示例和指令，提高工具调用准确率。
错误处理：OpenAILLM 中已加入简单异常捕获，实际生产环境可增加重试机制。
Token 限制：若对话历史过长，可能超出模型上下文长度，需实现截断或摘要。

完整项目结构（集成 OpenAI 后）

agent_project/
├── agent/
│   ├── __init__.py
│   ├── core/
│   │   ├── __init__.py
│   │   ├── agent.py
│   │   ├── perception.py
│   │   ├── planner.py
│   │   ├── reasoning.py      # 已优化 prompt
│   │   ├── executor.py
│   │   ├── memory.py
│   │   ├── reflector.py
│   │   ├── models.py
│   │   └── tool.py
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── calculator.py
│   │   ├── weather.py
│   │   └── email.py
│   ├── llm/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── mock.py            # 保留模拟 LLM 用于测试
│   │   └── openai.py          # 新增 OpenAI 实现
│   └── utils/
│       ├── __init__.py
│       └── logger.py
├── examples/
│   ├── simple_chat.py
│   └── task_execution.py      # 已更新使用 OpenAI
├── tests/
│   ├── test_agent.py
│   └── test_tools.py
├── requirements.txt            # 新增 openai
└── README.md