Agent/examples

Gemini Agent 测试成功 ✅

问题诊断与修复

🔍 发现的问题

1. 消息历史丢失

   • 问题：tool 消息缺少 name 字段
   • 位置：agent/runner.py:417
   • 修复：添加 name: tool_name 字段到 tool 消息

2. 架构设计不当

   • 问题：模型封装放在 example 中，应该在基础模块
   • 修复：创建 agent/llm/providers/gemini.py 模块

3. SDK 兼容性问题

   • 问题：google-generativeai SDK 对参数格式要求严格，与 OpenAI JSON Schema 不兼容
   • 修复：使用 HTTP REST API（httpx）代替 SDK

✅ 最终方案

1. HTTP API Provider（推荐）

文件：agent/llm/providers/gemini.py

特性：

• 使用 httpx 直接调用 Gemini REST API
• 完全控制消息格式转换
• 正确处理：
  • systemInstruction
  • functionCall / functionResponse
  • 连续 user 消息合并（Gemini 要求严格的 user/model 交替）

关键实现：

def _convert_messages_to_gemini(messages):
    """OpenAI -> Gemini 格式转换"""
    # 1. system -> systemInstruction
    # 2. assistant + tool_calls -> model + functionCall
    # 3. tool -> user + functionResponse
    # 4. 合并连续的 user 消息
    ...

def _convert_tools_to_gemini(tools):
    """工具定义转换，清理不支持的字段（default）"""
    ...

2. 使用方式

from agent.llm.providers.gemini import create_gemini_llm_call
from agent.runner import AgentRunner

# 创建 LLM 调用函数
gemini_llm_call = create_gemini_llm_call()

# 创建 Agent
runner = AgentRunner(
    tool_registry=registry,
    llm_call=gemini_llm_call
)

# 运行
async for event in runner.run(
    task="你的任务",
    model="gemini-2.5-pro",
    tools=["tool1", "tool2"],
    system_prompt="系统提示"
):
    # 处理事件
    ...

测试结果

任务："北京今天的天气怎么样？顺便帮我计算一下 15 * 8 等于多少。"

执行流程：

1. [Gemini HTTP] Converted 1 messages: ['user']
   → 调用工具: get_current_weather, calculate

2. [Gemini HTTP] Converted 3 messages: ['user', 'model', 'user']
   → 生成答案: "北京今天天气晴朗，15摄氏度。15 * 8 的计算结果是 120。"

✓ Trace 完成
  总 Tokens: 643

结果：✅ 完美运行，没有重复调用，正确结束

架构对比

❌ 之前（错误）

examples/
└── gemini_basic_agent.py  # 包含所有逻辑
    ├── 工具定义
    ├── Gemini SDK 调用
    └── Agent 运行

问题：

• 模型封装混在示例中
• 使用 SDK 导致兼容性问题
• 消息历史处理有bug

✅ 现在（正确）

agent/
├── llm/
│   └── providers/
│       └── gemini.py          # HTTP API 封装
├── tools/
│   └── registry.py            # 工具注册
└── runner.py                  # Agent 运行器

examples/
└── gemini_basic_agent.py      # 简洁的示例代码
    ├── 工具定义
    └── 使用 agent.llm.providers

优势：

• 清晰的模块分层
• 易于扩展（添加其他 provider）
• HTTP API 完全控制格式

依赖

pip install httpx python-dotenv

# 如果有代理
pip install 'httpx[socks]'

环境变量

# .env
GEMINI_API_KEY=your_api_key_here

参考

• Resonote 实现：/Users/sunlit/Code/Resonote/llm/providers/gemini.py
• Gemini REST API 文档：https://ai.google.dev/api/rest

下一步

可以扩展支持更多 LLM provider：

• OpenAI（已有 SDK）
• Claude（Anthropic API）
• DeepSeek
• 本地模型（Ollama）

每个 provider 只需实现相同的接口：

async def llm_call(messages, model, tools, **kwargs) -> Dict