Bee-Agent-Framework中Granite模型工具调用问题的分析与解决

在基于Bee-Agent-Framework开发AI助手应用时，开发者发现了一个关键问题：当使用Granite 3.1/3.0模型配合ToolCallingAgent时，系统无法正常调用工具功能。本文将深入分析问题原因并提供完整的解决方案。

问题现象

开发者在使用以下典型代码时发现异常：

llm = ChatModel.from_name("ollama:granite3.1-dense:8b")
agent = ToolCallingAgent(llm=llm, tools=[OpenMeteoTool()])
output = await agent.run(prompt="查询某地天气")

预期行为是Agent应该自动调用OpenMeteo天气查询工具，但实际输出显示：

1. Agent仅返回了如何调用工具的说明文本
2. 消息历史中没有任何工具调用记录
3. 最终未能获取真实天气数据

根本原因分析

通过深入排查，发现问题核心在于系统提示（System Prompt）的设计不当：

1. 默认提示不兼容：框架原使用的通用型系统提示与Granite模型的工具调用机制不兼容
2. 提示指令冲突：原有提示中"不要提及工具名称"的指令与工具调用需求直接矛盾
3. 模型特性差异：Granite模型需要特定的提示格式才能正确触发工具调用功能

解决方案

关键修改点

1. 采用Granite专用系统提示：

system_template = PromptTemplate(
    PromptTemplateInput(
        template="""Knowledge Cutoff Date: April 2024.
Today's Date: {current_date}
You are Granite, developed by IBM..."""
    )
)

2. 明确工具调用指令：

• 必须包含"<|tool_call|>"触发标记
• 明确工具不存在时的处理逻辑

3. 日期格式修正：

• 确保工具输入参数符合OpenMeteo API要求
• 处理日期时间格式转换问题

完整实现方案

async def get_weather():
    llm = ChatModel.from_name("ollama:granite3.1-dense:8b")
    
    templates = ToolCallingAgentTemplates(
        system=CustomSystemPromptTemplate()
    )
    
    agent = ToolCallingAgent(
        llm=llm,
        tools=[OpenMeteoTool()],
        templates=templates
    )
    
    output = await agent.run("某地当前天气")
    print(output.result.text)

技术要点总结

1. 模型适配性：不同大语言模型需要特定的提示工程才能发挥最佳效果
2. 工具调用机制：Granite模型采用<|tool_call|>标记触发工具调用
3. 参数验证：工具开发时必须严格定义参数格式和验证逻辑
4. 错误处理：需要完善工具调用失败时的回退机制

最佳实践建议

1. 为不同模型创建专用的提示模板
2. 工具开发时应该：
   • 明确定义参数格式
   • 提供详细的错误信息
   • 考虑多种使用场景
3. 实现完善的日志记录机制，方便调试工具调用过程

该问题的解决不仅修复了当前工具调用功能，更为框架后续支持更多大语言模型提供了重要参考。开发者在使用不同模型时，应当特别注意模型特定的提示工程要求。