Bee-Agent-Framework 中 ReActAgent 随机失败问题分析与解决方案

问题现象

在使用 Bee-Agent-Framework 的 ReActAgent 进行开发时，开发者遇到了一个随机失败的问题。测试代码在约 40% 的情况下会失败，且失败时错误信息为空，这给调试带来了困难。

问题分析

通过代码审查和测试日志分析，我们发现了几个关键问题点：

1. 内存操作未等待：初始代码中 memory.add 操作没有使用 await，可能导致异步操作未完成就继续执行后续代码。

2. 系统消息配置不当：开发者尝试直接添加 SystemMessage，而不是使用框架提供的模板配置方式。

3. 空提示问题：测试代码中设置了 prompt: ''，这会导致框架添加"Message: Empty message"到消息历史中，可能干扰代理的正常思考流程。

4. 模型输出格式问题：观察日志发现，模型有时会将最终答案(Final Answer)与思考过程(thought)混合在同一段落中输出，不符合框架预期的消息格式。

解决方案

1. 正确配置系统消息

使用框架提供的模板系统来配置系统消息，而不是手动添加 SystemMessage：

templates: {
  system: (template) =>
    template.fork((config) => {
      config.defaults.instructions = `You are a travel assistant. Always mention the airport name with also its short form.`;
    }),
}

2. 处理空提示问题

将空字符串提示改为 null，避免框架添加不必要的空消息提示：

const result = await agent.run({
  prompt: null,  // 修改前是 prompt: ''
})

3. 优化模型输出格式

在系统指令中添加明确的输出格式要求，引导模型产生结构化的响应：

config.defaults.instructions = `You are a travel assistant. Always mention the airport name, along with its short form.
IMPORTANT: The Final Answer should always be on a new line.`;

4. 确保异步操作完成

所有异步操作都应正确等待：

await memory.add(new UserMessage('Im james. wondering how do i get to the nearest airport from shah alam'))

最佳实践建议

1. 日志分析：充分利用框架提供的日志功能，观察代理的思考过程和错误发生时的上下文。

2. 测试设计：对于依赖外部模型的服务，考虑添加重试机制或设置更宽松的超时时间。

3. 消息结构验证：在关键断言前添加消息结构验证，确保模型输出符合预期格式。

4. 环境隔离：区分测试环境与实际调用环境，可以使用环境变量控制是否跳过实际模型调用。

总结

通过以上调整，我们解决了 Bee-Agent-Framework 中 ReActAgent 随机失败的问题。关键点在于正确配置系统消息、处理空提示、确保异步操作完成以及引导模型产生结构化输出。这些经验不仅适用于当前问题，也为框架的其他使用场景提供了参考。

对于基于大语言模型的代理开发，输出格式的控制和异步操作的处理是需要特别注意的方面。遵循框架的最佳实践，能够显著提高开发效率和系统稳定性。