Energy框架实战：从零构建具备记忆与工具调用能力的AI智能体

最近在AI应用开发领域，一个名为“Energy”的新项目引起了开发社区的广泛关注。它并非指代物理能源，而是一个由前OpenAI核心成员推出的、旨在降低AI工作流构建门槛的开源框架。对于许多开发者而言，虽然像LangChain、LlamaIndex这样的工具已经提供了强大的AI集成能力，但在实际构建一个稳定、高效且易于维护的AI应用时，依然会面临架构设计复杂、依赖管理繁琐、调试困难等挑战。Energy的出现，正是为了应对这些痛点，它试图提供一个更轻量、更专注的解决方案，让开发者能像搭积木一样快速组装和部署AI智能体（Agent）。

本文将深入解析Energy框架的核心设计理念、技术架构，并通过一个完整的实战案例，手把手教你如何从零开始使用Energy构建一个具备记忆和工具调用能力的AI助手。无论你是希望将大模型能力集成到现有业务中的后端工程师，还是对AI应用开发充满好奇的初学者，都能通过本文获得一套可直接复用的工程化方案。

1. Energy框架：核心理念与定位

在深入代码之前，我们首先要理解Energy试图解决什么问题，以及它在当前AI开发生态中的独特定位。

1.1 什么是Energy？

Energy是一个开源的Python框架，其核心目标是 简化AI智能体（Agent）和工作流的构建过程 。与一些大而全的框架不同，Energy强调“少即是多”的设计哲学，它不试图提供一个包含所有可能功能的庞然大物，而是专注于提供构建AI应用所需的最核心、最稳定的抽象层。

你可以把它想象成AI应用开发的“底盘”或“脚手架”。它定义了智能体如何运行、如何管理状态（记忆）、如何调用工具以及如何处理消息流。开发者基于这个稳固的底盘，可以更专注于业务逻辑和提示词工程，而不必重复造轮子处理底层的并发、流式传输或状态管理。

1.2 为什么需要另一个AI框架？

当前市场已有LangChain等成熟框架，Energy的差异化优势主要体现在以下几点：

1. 极简与专注 ：Energy的API设计非常简洁，概念清晰。它没有引入过多抽象层，减少了学习成本和认知负担。对于希望快速构建原型或中等复杂度应用的团队来说，上手更快。
2. 由经验丰富的团队打造 ：其创始团队来自OpenAI等顶尖AI公司，深谙生产环境中AI应用的痛点。因此，Energy在设计之初就考虑了可靠性、可观测性和易于调试等工程化需求。
3. 良好的可扩展性 ：虽然核心简洁，但Energy通过清晰的接口设计，允许开发者轻松集成自定义的工具、记忆存储后端以及不同的大模型提供商（如OpenAI、Anthropic、本地模型等）。
4. 对“智能体”的原生支持 ：Energy将“智能体”作为一等公民，内置了智能体运行循环、工具调用和结果处理的标准化流程，让构建一个能自主使用工具的AI变得非常简单。

1.3 核心概念解析

理解Energy，需要掌握以下几个核心概念：

• Agent（智能体） ：执行任务的核心实体。它接收用户输入，根据内部逻辑（通常是LLM驱动）决定行动步骤，例如调用工具、生成回复。
• Runtime（运行时） ：驱动智能体执行的核心引擎。它管理智能体的生命周期，处理输入输出流，是连接所有组件的枢纽。
• Memory（记忆） ：智能体的状态存储。可以是简单的对话历史，也可以是更复杂的向量数据库，用于实现长期记忆和上下文感知。
• Tool（工具） ：智能体可以调用的函数。可以是获取天气、查询数据库、执行计算等任何能力。Energy使工具的定义和调用标准化。
• Model（模型） ：底层的大语言模型。Energy通过统一的接口适配不同的模型提供商。

2. 环境准备与项目初始化

接下来，我们将进入实战环节。首先确保你的开发环境准备就绪。

2.1 系统与Python环境

• 操作系统 ：macOS / Linux / Windows (WSL2推荐)
• Python版本 ：>= 3.9 （建议使用3.10或3.11以获得最佳兼容性）
• 包管理工具 ：pip 或 poetry

2.2 创建虚拟环境与安装Energy

强烈建议使用虚拟环境来管理项目依赖，避免污染系统Python环境。

# 1. 创建项目目录并进入
mkdir energy-agent-demo && cd energy-agent-demo

# 2. 创建Python虚拟环境（以venv为例）
python -m venv venv

# 3. 激活虚拟环境
# macOS/Linux:
source venv/bin/activate
# Windows:
# venv\Scripts\activate

# 4. 升级pip
pip install --upgrade pip

# 5. 安装Energy核心库
pip install energy-ai

注意 ： energy-ai 是Energy框架在PyPI上的官方包名。安装时请确保网络通畅。

2.3 获取API密钥

Energy本身不提供大模型，你需要一个兼容OpenAI API的模型服务。这里我们以OpenAI为例，你也可以使用Azure OpenAI或本地部署的兼容API服务（如Ollama、vLLM）。

1. 访问OpenAI平台 (platform.openai.com) 并注册登录。
2. 在API Keys页面，创建一个新的密钥并妥善保存。

安全提示 ：切勿将API密钥直接硬编码在代码中或提交到版本控制系统（如Git）。接下来我们会使用环境变量来管理。

# 在终端中设置环境变量（临时，仅当前会话有效）
# macOS/Linux:
export OPENAI_API_KEY='你的-api-key-here'
# Windows (PowerShell):
# $env:OPENAI_API_KEY='你的-api-key-here'

# 更推荐的做法是创建 .env 文件（需要安装python-dotenv）

3. Energy核心组件与配置详解

安装完成后，我们来逐一拆解Energy的核心组件，并学习如何配置它们。

3.1 配置大模型连接

Energy通过 OpenAI 类来连接模型服务。我们需要在代码中初始化它。

# 文件：config.py
import os
from energy import OpenAI

# 从环境变量读取API密钥
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
    raise ValueError("请设置 OPENAI_API_KEY 环境变量")

# 初始化OpenAI客户端，指定使用的模型
# 默认是 gpt-3.5-turbo，可根据需要更换为 gpt-4 等
llm_client = OpenAI(
    api_key=api_key,
    model="gpt-3.5-turbo",
    # 可选参数：设置API基础URL，用于连接非官方OpenAI端点（如Azure OpenAI、Ollama）
    # base_url="https://your-custom-endpoint.com/v1"
)

3.2 定义工具（Tools）

工具是智能体能力的延伸。定义一个工具就是定义一个Python函数，并用 @tool 装饰器进行装饰。Energy会自动为函数生成描述，供LLM理解其用途。

# 文件：tools.py
from energy import tool
from datetime import datetime

@tool
def get_current_time(timezone: str = "UTC") -> str:
    """
    获取指定时区的当前时间。

    Args:
        timezone: 时区，例如 'Asia/Shanghai'。默认为 'UTC'。

    Returns:
        格式化的当前时间字符串。
    """
    # 这是一个简化示例，实际应用中可能需要使用pytz库
    now = datetime.utcnow()
    return f"The current time in {timezone} is: {now.strftime('%Y-%m-%d %H:%M:%S')} UTC"

@tool
def calculate_sum(numbers: list[float]) -> float:
    """
    计算一组数字的总和。

    Args:
        numbers: 需要求和的数字列表。

    Returns:
        所有数字的总和。
    """
    return sum(numbers)

3.3 构建记忆系统（Memory）

记忆让智能体拥有上下文。Energy提供了 Memory 类来管理对话历史。默认使用内存存储，对于生产环境，你可以扩展它以使用数据库。

# 文件：memory_setup.py
from energy import Memory

# 创建一个简单的内存记忆实例
# 它可以自动存储和检索最近的对话历史
memory = Memory()

# 你可以配置记忆的容量（保留多少轮对话）
# memory = Memory(max_messages=20)

3.4 组装智能体（Agent）

这是最核心的一步。我们将模型、工具和记忆组合起来，创建一个智能体实例。

# 文件：agent_builder.py
from energy import Agent
from config import llm_client
from tools import get_current_time, calculate_sum
from memory_setup import memory

# 创建智能体
agent = Agent(
    name="Assistant",
    model=llm_client,      # 绑定我们配置好的模型客户端
    memory=memory,         # 绑定记忆系统
    tools=[get_current_time, calculate_sum], # 绑定可用的工具列表
    instructions="""
    你是一个乐于助人的AI助手。你可以回答用户的问题，并使用你拥有的工具来获取信息或进行计算。
    当用户的问题涉及时间或计算时，你应该主动调用相应的工具。
    你的回答应该友好、清晰且准确。
    """ # 给智能体的系统指令，定义其角色和行为
)

4. 完整实战：构建一个多功能AI助手

现在，让我们将以上所有部分整合起来，创建一个完整的、可运行的AI助手应用。

4.1 项目结构

首先，建立清晰的项目目录结构：

energy-agent-demo/
├── .env                    # 存储环境变量（需自行创建，.gitignore忽略）
├── config.py               # 模型配置
├── tools.py                # 自定义工具定义
├── memory_setup.py         # 记忆系统配置
├── agent_builder.py        # 智能体组装
├── main.py                 # 主运行程序
└── requirements.txt        # 项目依赖

requirements.txt 内容如下：

energy-ai>=0.1.0
python-dotenv>=1.0.0
openai>=1.0.0  # 如果你使用OpenAI官方SDK

4.2 主程序实现

主程序 main.py 负责启动智能体并与用户进行交互。

# 文件：main.py
import asyncio
import sys
from dotenv import load_dotenv
from agent_builder import agent

# 加载 .env 文件中的环境变量
load_dotenv()

async def chat_with_agent():
    """
    与智能体进行异步对话的主循环。
    """
    print("🤖 Energy AI 助手已启动！输入 'quit' 或 'exit' 退出。")
    print("-" * 40)

    while True:
        try:
            # 获取用户输入
            user_input = input("\n👤 你: ").strip()

            if user_input.lower() in ['quit', 'exit', 'q']:
                print("👋 再见！")
                break
            if not user_input:
                continue

            # 调用智能体处理用户输入
            print("🤖 助手: ", end="", flush=True)
            response = await agent.run(user_input)

            # 打印助手的完整响应
            print(response)

        except KeyboardInterrupt:
            print("\n\n👋 程序被中断。")
            break
        except Exception as e:
            print(f"\n❌ 发生错误: {e}")
            # 在实际应用中，这里应该记录日志，而不是直接打印给用户

if __name__ == "__main__":
    # 检查必要的环境变量
    import os
    if not os.getenv("OPENAI_API_KEY"):
        print("错误: 未找到 OPENAI_API_KEY 环境变量。")
        print("请在 .env 文件中设置，或通过命令行导出。")
        sys.exit(1)

    # 运行异步主函数
    asyncio.run(chat_with_agent())

4.3 运行与验证

1. 创建 .env 文件 ：在项目根目录下创建 .env 文件，并填入你的API密钥。

   OPENAI_API_KEY=sk-你的真实密钥
   

   务必确保 .env 在 .gitignore 中，避免密钥泄露。

2. 安装依赖 ：在激活的虚拟环境中运行 pip install -r requirements.txt 。

3. 启动助手 ：在终端运行 python main.py 。

4. 进行对话测试 ：

   🤖 Energy AI 助手已启动！输入 'quit' 或 'exit' 退出。
   ----------------------------------------
   
   👤 你: 你好，现在几点了？
   🤖 助手: 我将为您查询当前时间。
   [调用工具：get_current_time]
   The current time in UTC is: 2023-10-27 08:15:30 UTC
   
   👤 你: 请计算一下 12.5, 7.8, 和 23.1 的和。
   🤖 助手: 我来为您计算这些数字的总和。
   [调用工具：calculate_sum]
   数字 [12.5, 7.8, 23.1] 的总和是 43.4。
   
   👤 你: 我们刚才聊了什么？
   🤖 助手: 根据我们的对话历史，您首先询问了当前时间，我为您查询了UTC时间。接着您让我计算了12.5, 7.8和23.1这三个数字的总和，结果是43.4。
   

   如上所示，智能体成功调用了工具，并且利用记忆回答了关于历史对话的问题。

4.4 结果说明

通过这个简单的示例，我们实现了一个具备以下能力的AI助手：

1. 基础对话 ：理解并回应自然语言。
2. 工具调用 ：根据用户意图，自动选择并执行预定义的 get_current_time 和 calculate_sum 工具。
3. 对话记忆 ：能记住当前的对话上下文，并据此回答问题。
4. 流式交互 ：通过简单的命令行界面与用户进行多轮对话。

这一切都建立在Energy框架提供的基础设施之上，我们无需手动处理工具调用的格式转换、记忆的存储与检索、以及与LLM API的复杂交互。

5. 常见问题与排查思路

在开发和使用Energy过程中，你可能会遇到一些典型问题。下表列出了常见错误及其解决方法：

6. 最佳实践与工程化建议

将Energy用于实际项目时，遵循以下最佳实践可以提升应用的稳定性、可维护性和可扩展性。

6.1 项目结构与代码组织

• 分层设计 ：将配置、工具定义、记忆逻辑、智能体组装和主业务逻辑分离到不同文件，如上文示例所示。这符合单一职责原则。
• 依赖注入 ：通过函数参数或配置文件传递 api_key 、 model_name 等可变配置，避免硬编码。
• 使用配置管理 ：对于生产环境，使用专业的配置管理库（如 pydantic-settings ）来管理模型端点、密钥、超时时间等所有配置项。

6.2 工具设计与开发

• 清晰的文档 ：为每个工具函数编写详尽、准确的docstring。LLM依赖这些描述来理解何时以及如何调用工具。
• 健壮的错误处理 ：在工具函数内部使用 try-except 块，捕获可能出现的异常（如网络错误、数据格式错误），并返回结构化的错误信息，而不是让整个智能体崩溃。
• 类型提示 ：充分利用Python的类型提示（Type Hints），这不仅能帮助IDE进行代码补全和检查，也能为Energy提供更准确的参数信息。
• 工具分类 ：当工具数量增多时，可以按功能模块组织（如 weather_tools.py , data_query_tools.py ），并在 agent_builder.py 中统一导入。

6.3 记忆与状态管理

• 选择持久化存储 ：对于需要长期记忆或跨会话记忆的应用，应将 Memory 的后端从默认的内存存储替换为数据库（如SQLite、PostgreSQL）或向量数据库（如Chroma, Weaviate）。Energy通常允许你通过继承 Memory 类来实现自定义存储。
• 控制上下文长度 ：大模型有上下文窗口限制。合理设置 max_messages 或实现摘要功能，将过长的对话历史进行压缩，只保留关键信息，以避免超出令牌限制。
• 分离记忆与工具 ：将与工具调用相关的临时状态和与用户对话相关的长期记忆分开管理。

6.4 生产环境部署

• API密钥安全 ：永远不要将密钥提交到代码仓库。使用环境变量、密钥管理服务（如AWS Secrets Manager, HashiCorp Vault）或云平台提供的安全配置。
• 设置超时与重试 ：在初始化 OpenAI 客户端时，配置合理的超时（ timeout ）和重试策略（ max_retries ），以应对网络波动或上游服务不稳定。
• 实现日志与监控 ：为智能体的运行过程添加详细的日志记录，特别是工具调用、模型响应和错误信息。这对于调试和了解智能体行为至关重要。
• 限流与降级 ：如果你的应用面向大量用户，需要对模型API的调用进行限流，并设计降级方案（例如，当主要模型不可用时，切换到更便宜的模型或返回缓存结果）。

6.5 测试与评估

• 单元测试工具函数 ：确保每个工具函数在各种输入下都能正确工作。
• 集成测试智能体流程 ：编写测试用例，模拟用户输入，验证智能体是否能正确调用工具并生成预期回复。
• 评估智能体表现 ：建立一套评估体系（可以是自动化测试或人工评估），定期检查智能体在关键任务上的准确性和可靠性。

Energy框架为AI应用开发提供了一个坚实而灵活的起点。它通过简化的抽象，让开发者能更专注于创造有价值的AI功能，而非陷入基础设施的泥潭。从今天的简单助手开始，你可以逐步探索更复杂的多智能体协作、工作流编排等高级特性，将AI能力更深度、更可靠地集成到你的产品之中。