跳转至
编辑此页 查看本页的源代码

Kimi Web Search Agent 🔍

一个基于 Kimi API 的智能搜索 Agent，能够理解用户问题，自动进行网络搜索并总结答案。

📋 项目概述

本项目实现了一个自主式 AI Agent，利用 Kimi（Moonshot AI）的内置 Web 搜索工具（search 和 crawl），能够：

  • 🤔 智能理解：分析用户问题，识别关键信息需求
  • 🔍 自动搜索：使用 Kimi 的内置 $web_search 工具获取实时网络信息
  • 🔄 迭代搜索：可以多次调用搜索工具获取更全面的信息
  • 📝 智能总结：综合多源信息，生成准确、全面的答案

🏗️ 架构设计

graph TD A[用户问题] --> B{Agent 思考} B -->|需要搜索| C[调用 $web_search 工具] C --> D[Kimi 搜索引擎] D --> E[返回搜索结果] E --> F{信息充足?} F -->|否| G[继续调用 $web_search] G --> H[获取更多信息] H --> F F -->|是| I[生成最终答案] B -->|不需要搜索| J[直接回答]

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置 API Key

从 Moonshot AI 平台 获取 API Key，然后设置环境变量：

export MOONSHOT_API_KEY='your-api-key-here'

或创建 .env 文件：

MOONSHOT_API_KEY=your-api-key-here

注意: 为了向后兼容，系统也支持使用 KIMI_API_KEY 环境变量。

通用兜底（OpenRouter）: 若未设置 MOONSHOT_API_KEY/KIMI_API_KEY 但设置了 OPENROUTER_API_KEY，请求会自动改走 OpenRouter，使用 OPENROUTER_MODEL（默认 openai/gpt-5.6-luna）。重要限制：Kimi 内置的 $web_search 工具是 Moonshot 专有能力， 在 OpenRouter 上不可用——因此兜底模式下模型仅凭自身知识作答，没有实时联网搜索。 如需真正的联网搜索，请使用 Moonshot 主 key。

3. 运行 Agent

main.py 提供了完整的命令行接口（中文帮助）。查看全部参数：

python main.py --help
参数 说明 默认值
query 要提问的问题（位置参数）；省略则进入交互模式 无
--provider 搜索后端：kimi（调用内置 $web_search，需 API Key）/ offline-demo（离线示例轨迹） kimi
--model 模型名称 kimi-k3
--max-steps 最大 ReAct 迭代次数 5
--base-url API 基础 URL https://api.moonshot.cn/v1
--api-key Kimi API Key（默认读环境变量） 环境变量
--output, -o 将问题、ReAct 轨迹与答案保存为 JSON 无
--quiet 不实时打印 ReAct 轨迹 打印

离线演示 ReAct 循环（无需 API Key，回放示例轨迹，直观展示“想→做→看”）： 

python main.py --provider offline-demo

交互模式（持续对话）： 

python main.py

单次问答（运行时逐步打印思考/行动/观察轨迹）： 

python main.py "2024年诺贝尔物理学奖获得者是谁？"
python main.py "比特币现价" --max-steps 3 --output result.json

快速体验（引导式交互）： 

python quickstart.py

高级示例： 

python examples.py

💡 运行时会实时打印 ReAct 轨迹：💭 思考 → 🔧 行动（调用 $web_search）→ 👀 观察（搜索结果）→ ✅ 最终答案，对应本章讲的“想→做→看”循环。agent.get_trace() 可获取结构化轨迹，--output 可将其存为 JSON。

📖 使用示例

基础使用

from agent import WebSearchAgent
from config import Config

# 创建 Agent
agent = WebSearchAgent(api_key=Config.get_api_key())

# 提问并获取答案
question = "Python 3.12 有哪些新特性？"
answer = agent.search_and_answer(question)
print(answer)

高级功能

运行高级示例：

python examples.py

包含以下功能： - 📦 批量搜索：同时搜索多个问题 - 🎯 带上下文搜索：提供背景信息进行更精准的搜索 - ⚖️ 比较搜索：搜索并比较多个项目 - ✅ 事实核查：验证陈述的真实性 - 📚 研究助手：深度研究某个主题

🛠️ 核心组件

agent.py - 核心 Agent 实现

  • WebSearchAgent: 主要的 Agent 类
  • search_and_answer(): 执行 ReAct 循环并生成答案的主方法
  • get_trace(): 返回上一次运行的结构化 ReAct 轨迹（思考/行动/观察/最终答案）
  • _chat(): 与 Kimi API 进行对话交互
  • _get_system_prompt(): 获取系统提示，定义 Agent 行为
  • _get_tools(): 定义可用的工具（$web_search）
  • search_impl(): 搜索实现的抽象层，便于扩展
  • format_trace_step(): 将一条轨迹步骤渲染为可读文本
  • run_offline_demo(): 离线回放示例轨迹，无需 API Key 即可演示 ReAct 循环

config.py - 配置管理

  • API 配置
  • 模型选择
  • 搜索参数设置

main.py - 主程序入口

  • build_parser(): argparse 命令行接口（中文帮助，见 --help）
  • run_interactive_mode(): 交互式对话模式
  • run_single_question(): 单次问答模式
  • 离线演示模式（--provider offline-demo）与 JSON 结果输出（--output）
  • 会话管理

quickstart.py - 快速体验脚本

  • demo_search(): 演示搜索功能
  • interactive_mode(): 简化的交互模式
  • 彩色输出和用户引导
  • API Key 配置检查

examples.py - 高级示例

  • AdvancedWebSearchAgent: 扩展功能的 Agent 类
  • batch_search(): 批量处理多个问题
  • search_with_context(): 带上下文的搜索
  • comparative_search(): 比较多个项目
  • fact_check(): 事实验证功能
  • example_research_assistant(): 深度研究示例

🔧 配置选项

配置项 说明 默认值
MOONSHOT_API_KEY Moonshot AI API 密钥 必填
KIMI_API_KEY 旧版 API 密钥变量名（向后兼容） 可选
KIMI_BASE_URL API 基础 URL https://api.moonshot.cn/v1
DEFAULT_MODEL 默认模型 kimi-k3
MAX_SEARCH_ITERATIONS 最大搜索迭代次数（Config 中设置） 5
SEARCH_TIMEOUT 搜索超时时间（秒） 30
temperature 控制生成内容的创造性 0.6

📊 技术特点

核心技术

  • Kimi API: 使用 Moonshot AI 的最新 Kimi K3 模型（kimi-k3，原生联网搜索的推理模型）
  • 内置工具调用: 利用 Kimi 的 $web_search 内置函数
  • 迭代式搜索: 支持多轮搜索直到获得充分信息（最多5次迭代）
  • 上下文管理: 维护完整对话历史，支持连续对话
  • 温度控制: 支持调整生成内容的创造性（temperature 参数）

优势

  • ✅ 实时信息: 获取最新的网络信息
  • ✅ 智能理解: 理解用户意图，精准搜索
  • ✅ 结构化输出: 生成组织良好的答案
  • ✅ 可扩展性: 易于添加新功能和工具

📝 开发计划

  • [ ] 添加异步搜索支持（使用 aiohttp）
  • [ ] 实现搜索结果缓存机制
  • [ ] 支持更多搜索后端（通过 search_impl 扩展）
  • [ ] 支持多语言搜索
  • [ ] 添加搜索结果质量评分
  • [ ] 实现搜索历史记录
  • [ ] 集成重试机制（使用 tenacity）
  • [ ] 优化长对话的上下文管理

📄 许可证

MIT License

🔗 相关链接

⚠️ 注意事项

  1. API 限制: 请注意 Kimi API 的调用限制和配额
  2. 搜索质量: 搜索结果质量依赖于 Kimi 的搜索能力
  3. 响应时间: 网络搜索可能需要一定时间，请耐心等待
  4. 内容准确性: Agent 会尽力提供准确信息，但建议对重要信息进行二次验证

💡 使用建议

  1. 明确问题: 提供清晰、具体的问题以获得更好的答案
  2. 提供上下文: 必要时提供背景信息帮助 Agent 理解
  3. 迭代优化: 如果答案不满意，可以提供更多细节重新提问
  4. 合理期望: Agent 基于搜索结果回答，可能无法回答所有问题

作者: AI Agent 实战训练营
版本: 1.0.0
更新时间: 2024