什么是 miniEvoAgent？
miniEvoAgent 是一个紧凑的 Python 框架，用于学习如何构建和改进基于 LLM 的智能体。它受到 EvoAgentX 的启发，保留了智能体执行、工具调用、评估、提示词重写和自我进化等核心概念，同时移除了大型智能体框架的复杂性。
该软件包目前名为 evo_repro。其刻意保持精简的设计，使每种机制都更易于阅读、测试和扩展。它不提供工作流图、记忆、可视化编辑器、基准测试适配器或庞大的工具生态系统，而是专注于透明的单动作智能体与提示词进化循环。
框架的工作原理
miniEvoAgent 应用由几个职责明确的组件构成：
- PromptTemplate：将任务输入插入提示词模板。
- Action：调用 LLM，可选择执行多轮工具调用，并解析最终响应。
- Agent：封装一个动作并返回结构化消息。
- 评估器函数：使用精确匹配、词元级 F1 和准确率为问答预测结果评分。
- PromptRewriter：使用优化器 LLM，根据具体的反馈示例提出修改后的提示词。
- PromptSelector：在同一开发集上比较父提示词及其候选提示词，并保留表现更好的一个。
- evolve：重复执行训练、生成反馈、重写、评估和选择流程。
主要功能
- 最小化且可检查的单动作智能体抽象。
- 可通过环境变量或本地
.env文件配置的 OpenAI 兼容 LLM 适配器。 - 支持多轮工具执行的 OpenAI 风格函数工具。
- 通过优化器 LLM 实现由反馈驱动的提示词重写。
- 基于开发集的选择机制，仅在候选提示词提升分数时才接受它。
- 包含训练执行记录、重写输入、开发集分数和选择决策的进化轨迹。
- 用于在不调用远程 API 的情况下测试框架行为的确定性模拟 LLM。
安装 miniEvoAgent
环境要求
请使用 Python 3.10 或更高版本。以下 PowerShell 命令会进入代码仓库、创建并激活虚拟环境、更新 pip，然后以可编辑模式安装软件包：
cd D:\Projects\RSIProject\student-project\Evo-repro
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .在学习或修改源代码时，可编辑安装非常有用，因为对本地软件包的更改会立即在 Python 环境中生效。
配置 OpenAI 兼容的 LLM
默认的 OpenAILLM 适配器会从环境变量或本地 .env 文件读取设置。在 PowerShell 中，按如下方式设置 API 密钥和模型：
$env:OPENAI_API_KEY="your_api_key"
$env:OPENAI_MODEL="gpt-4o-mini"如果使用其他 OpenAI 兼容服务，请设置其端点：
$env:OPENAI_BASE_URL="https://your-compatible-endpoint/v1"或者，将 .env.example 复制为 .env，并在其中添加相同的配置值。
构建基础问答智能体
基础智能体需要一个 LLM、一个提示词模板、一个输出解析器和一个动作。随后，智能体会通过简单的执行接口公开这些组成部分。
from evo_repro import Action, Agent, OpenAILLM, PromptTemplate, TextOutputParser
llm = OpenAILLM()
action = Action(
name="answer_question",
prompt_template=PromptTemplate(
template="Answer the following question:\n\n{question}"
),
llm=llm,
output_parser=TextOutputParser(),
)
agent = Agent(
name="qa_agent",
description="Answers a single user question.",
action=action,
)
message = agent.execute({
"question": "What is Retrieval-Augmented Generation?"
})
print(message.content)传递给 agent.execute 的 question 键对应模板中的 {question} 占位符。动作会渲染提示词，将其发送给已配置的 LLM，解析返回的文本，并将结果封装为结构化消息。
你也可以运行随附的示例：
python examples\simple_agent.py添加可调用的 Python 工具
miniEvoAgent 工具是对 Python 函数的轻量封装。每个工具都会提供一个供模型执行函数调用的 JSON Schema，并返回结构化的 ToolResult。
该软件包包含 get_word_length_tool，可通过动作的 tools 参数将其附加到动作：
from evo_repro import Action, Agent, OpenAILLM, PromptTemplate, TextOutputParser
from evo_repro import get_word_length_tool
agent = Agent(
name="tool_agent",
description="Answers a question and can use tools.",
action=Action(
name="answer_with_tools",
prompt_template=PromptTemplate(
template=(
"Answer the following question. "
"Use tools when useful:\n\n{question}"
)
),
llm=OpenAILLM(),
output_parser=TextOutputParser(),
tools=[get_word_length_tool],
),
)
message = agent.execute({
"question": 'How many characters are in "retrieval"?'
})
print(message.content)
print(message.metadata["tool_results"])当 LLM 请求受支持的函数时，动作会执行该函数，并将工具结果返回到对话中。在解析模型的最终输出之前，动作支持多轮执行这一过程。可以通过 message.metadata["tool_results"] 获取工具执行记录。
使用以下命令运行随附的工具示例：
python examples\tool_agent.py理解提示词自我进化
自我进化系统通过受控的反馈与评估循环改进提示词：
- 在训练示例上运行当前提示词。
- 将预测结果、预期标签和评估指标转换为反馈示例。
- 请求由优化器 LLM 支持的
PromptRewriter生成一个候选提示词。 - 在同一开发集上评估父提示词和候选提示词。
- 使用
PromptSelector保留表现更好的提示词。 - 按照配置的代数重复该流程。
如需运行一代，请使用 evolve_once(...)，它会返回一个 EvolutionRoundTrace。如需运行多代，请使用 evolve(...)，它会同时返回最终提示词和完整历史记录。
无需远程模型即可审查进化过程
代码仓库包含一个使用模拟 LLM 行为的确定性审查示例：
python examples\evolution_audit.py输出会显示每一代的父提示词、训练记录、重写输入、候选提示词、开发集对比，以及接受或拒绝决策。这样便可检查优化过程，而不是将提示词改进视为隐藏操作。
评估问答预测结果
内置评估器提供三种有意保持简单的问答指标：
- 精确匹配：根据评估器的比较方式，检查预测结果是否与预期答案完全一致。
- 词元级 F1：衡量预测结果与预期答案之间的词元重叠程度。
- 准确率：报告正确预测所占的比例。
这些指标旨在验证和演示进化循环。项目说明指出，之后可以将它们替换为适用于特定基准测试或任务的评估器。
运行测试套件
在代码仓库根目录执行所有测试：
python -m pytest该精简测试套件涵盖智能体、工具和进化行为。框架尽可能使用模拟 LLM 实现，因此无需 API 密钥或远程模型调用即可验证大部分框架逻辑。
高级技巧
先进行确定性测试，再开展在线实验
修改提示词选择、工具处理或进化逻辑时，请先从模拟 LLM 示例和测试开始。确定性输出可以使故障稳定复现，并有助于区分框架缺陷与在线模型响应的变化。
检查每一代的轨迹
不要只根据最终提示词评估一次进化运行。请检查记录的训练执行过程、提供给重写器的反馈、候选提示词、开发集分数和选择决策。这些记录会揭示候选提示词被接受或拒绝的原因。
明确区分训练集和开发集的作用
进化过程根据训练示例生成重写反馈，但会在同一开发集上比较父提示词和候选提示词。准备实验时应保持这种划分，以确保选择过程遵循框架的预期流程。
检查结构化工具结果
对于启用工具的智能体，除最终文本外，还应检查 message.metadata["tool_results"]。这有助于确认模型是否选择了工具、执行是否成功，以及返回了什么结构化结果。
按需使用兼容的自定义端点
通过 OPENAI_BASE_URL 设置，可以让 OpenAILLM 使用 OpenAI 兼容端点。请确保 API 密钥和所选模型符合该端点的要求。
了解项目当前的范围
miniEvoAgent 的定位刻意比 EvoAgentX 更精简。目前它并未声称支持工作流图、多智能体编排、记忆、人机协作功能、基准测试集成、可视化编辑或广泛的工具集。路线图包括更丰富的工作流组合、更多提供商适配器、基准测试加载器、可复用工具集、JSON 持久化和补充文档，但这些属于规划中的功能，而不是当前已提供的功能。
重新分发前检查许可证
项目当前未包含许可证文件。在发布或重新分发代码之前，请添加适当的许可证。
总结
miniEvoAgent 为学习 LLM 智能体工程提供了一条小巧且可测试的路径。借助 evo_repro 软件包，你可以构建由提示词驱动的智能体、添加 OpenAI 风格的函数工具、衡量问答性能、根据失败案例重写提示词，并通过开发集评估保留改进。其紧凑的架构和确定性示例尤其适合研究智能体执行与提示词进化的内部工作原理。