Kimi Web Search Agent / Kimi 网络搜索 Agent¶

Autonomous ReAct web-search agent on Kimi K3 using Moonshot's official Formula API (multi-round search + synthesis). 配套《深入理解 AI Agent》第 1 章 实验 1-2 ★：Kimi K3 原生 Agent 能力。

← Chapter 1 index / 返回第 1 章目录 · 📖 Read the chapter / 读本章正文（EN）

English¶

Overview¶

This project implements an autonomous AI agent that uses Kimi K3 and Moonshot's official moonshot/web-search:latest Formula to:

Understand the question: analyze the user query and identify information needs
Search automatically: fetch live web information through the standard web_search function declaration and Formula Fibers
Iterate: call search multiple times until evidence is sufficient
Synthesize: combine multi-source results into a clear, accurate answer

It demonstrates the “Model as Agent” idea and the ReAct loop (think → act → observe).

Exact Formula route¶

Kimi K3's current official hosted-search route is not the legacy builtin_function passthrough. Every independent question performs this exact provider-controlled sequence:

GET /v1/formulas/moonshot/web-search:latest/tools obtains Moonshot's authoritative standard function declaration named web_search.
The declaration is sent unchanged to POST /v1/chat/completions with the conversation. Kimi decides whether and how often to call it.
For each model tool call, the implementation passes the returned name and raw serialized arguments unchanged to POST /v1/formulas/moonshot/web-search:latest/fibers.
Only HTTP-successful Fibers with status == "succeeded" are accepted. Their context.output (or encrypted output) is returned as the matching tool result.

The search engine remains hosted by Moonshot; this repository does not replace it with a local or third-party search implementation. See the official Formula tool guide and web-search guide.

Architecture¶

graph TD A[User question] --> B{Agent thinks} B -->|needs search| C[Model calls web_search] C --> D[POST Formula Fiber] D --> E[Return Fiber output] E --> F{Enough info?} F -->|no| G[Call web_search again] G --> H[More information] H --> F F -->|yes| I[Final answer] B -->|no search needed| J[Answer directly]

Quick Start¶

1. Install dependencies¶

# Recommended from the repository root: use the shared Chapter 1 environment
uv sync --locked --extra ch1

# Activate it before changing directories:
# macOS/Linux:
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
# Windows cmd: .venv\Scripts\activate.bat

# pip fallback when uv is not installed:
# python -m pip install -e ".[ch1]"

# Enter this experiment directory for the commands below
cd chapter1/web-search-agent

# Single-project compatibility path, still supported during migration:
# python -m pip install -r requirements.txt

2. Configure API Key¶

Get a key from the Moonshot AI platform, then set:

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

Or create a .env file:

MOONSHOT_API_KEY=your-api-key-here

Note: For backward compatibility, KIMI_API_KEY is also accepted.

Universal OpenRouter fallback: if neither MOONSHOT_API_KEY nor KIMI_API_KEY is set but OPENROUTER_API_KEY is, requests go through OpenRouter using OPENROUTER_MODEL (default openai/gpt-5.6-luna). Moonshot Formula declarations and Fibers are not exposed through OpenRouter, so fallback mode answers from model knowledge without live Formula search. It is useful for interface diagnostics only and cannot satisfy Experiment 1-2 acceptance.

3. Run the Agent¶

main.py provides a full CLI (Chinese help). List all flags:

python main.py --help

Flag	Description	Default
`query`	Question (positional); omit for interactive mode	none
`--provider`	Backend: `kimi` (Moonshot Formula `web_search`, needs API key) / `offline-demo` (offline sample trace)	`kimi`
`--model`	Model name	`kimi-k3`
`--max-steps`	Max ReAct iterations	`5`
`--base-url`	API base URL	`https://api.moonshot.cn/v1`
`--api-key`	Kimi API key (else from env)	env
`--output`, `-o`	Save question, ReAct trace, and answer as JSON	none
`--quiet`	Do not stream ReAct trace live	stream on

Offline ReAct demo (no API key; replays a sample trace to show think → act → observe):

python main.py --provider offline-demo

Interactive mode (ongoing dialogue):

python main.py

Single question (streams think / act / observe steps):

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

Guided quickstart:

python quickstart.py

Advanced examples:

python examples.py

At runtime the agent prints a ReAct trace: 💭 think → 🔧 act (web_search) → 👀 observe (Formula output) → ✅ final answer. Use agent.get_trace() for a structured trace, or --output to save JSON.

Usage Examples¶

Basic usage¶

from agent import WebSearchAgent
from config import Config

# Create Agent
agent = WebSearchAgent(api_key=Config.get_api_key())

# Ask and get an answer
question = "Python 3.12 有哪些新特性？"
answer = agent.search_and_answer(question)
print(answer)

Advanced features¶

python examples.py

Includes:

Batch search: multiple questions in one run
Context-aware search: supply background for sharper queries
Comparative search: search and compare items
Fact check: verify claims
Research assistant: deeper topic research

Core Components¶

`agent.py` — core agent¶

WebSearchAgent: main agent class
search_and_answer(): run the ReAct loop and produce an answer
get_trace(): structured ReAct trace of the last run (think / act / observe / final)
_chat(): chat with the Kimi API
_get_system_prompt(): system prompt defining agent behavior
_get_tools(): tool definitions ($web_search)
search_impl(): search implementation layer (extension point)
format_trace_step(): render one trace step as readable text
run_offline_demo(): offline sample-trace replay (no API key)

`config.py` — configuration¶

API settings
Model selection
Search parameters

`main.py` — entry point¶

build_parser(): argparse CLI (Chinese help; see --help)
run_interactive_mode(): interactive dialogue
run_single_question(): one-shot Q&A
Offline demo (--provider offline-demo) and JSON output (--output)
Session management

`quickstart.py` — guided demo¶

demo_search(): demo search
interactive_mode(): simplified interactive mode
Colored output and user guidance
API key checks

`examples.py` — advanced demos¶

AdvancedWebSearchAgent: extended agent
batch_search(): batch questions
search_with_context(): context-aware search
comparative_search(): multi-item comparison
fact_check(): fact verification
example_research_assistant(): deep research example

Configuration Options¶

Item	Description	Default
`MOONSHOT_API_KEY`	Moonshot AI API key	required
`KIMI_API_KEY`	Legacy key env name (compat)	optional
`KIMI_BASE_URL`	API base URL	`https://api.moonshot.cn/v1`
`DEFAULT_MODEL`	Default model	`kimi-k3`
`MAX_SEARCH_ITERATIONS`	Max search iterations (in Config)	5
`SEARCH_TIMEOUT`	Search timeout (seconds)	30
`temperature`	Generation creativity	0.6

Technical Notes¶

Core stack¶

Kimi API: Moonshot Kimi K3 (kimi-k3), a reasoning model with native web search
Built-in tool calling: Kimi $web_search built-in function
Iterative search: up to 5 rounds until information is sufficient
Context management: full dialogue history for multi-turn chat
Temperature control: adjustable creativity

Strengths¶

Live information: up-to-date web results
Intent understanding: search aligned with the question
Structured answers: well-organized responses
Extensible: easy to add tools via search_impl and related hooks

Development ideas (not implemented)¶

[ ] Async search (e.g. aiohttp)
[ ] Result caching
[ ] More search backends via search_impl
[ ] Multilingual search
[ ] Result quality scoring
[ ] Search history
[ ] Retries (e.g. tenacity)
[ ] Better long-dialogue context management

Caveats¶

API limits: respect Kimi quotas and rate limits
Search quality: depends on Kimi’s search capability
Latency: web search can take time
Accuracy: double-check critical facts; the agent may still err

Usage tips¶

Ask clearly: specific questions get better answers
Give context: background helps when needed
Iterate: refine with more detail if the first answer is weak
Set expectations: answers are grounded in search results and may not cover everything

Links¶

中文¶

概述¶

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

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

对应书中实验 1-2 ★：Kimi K3 原生 Agent 能力，体现“模型即 Agent”与 ReAct（想 → 做 → 看）循环。

Kimi 联网搜索服务状态¶

本示例依赖 Kimi 托管的 $web_search 服务。本仓库只会将内置工具返回的参数原样传回 Kimi，并不会在本地执行搜索引擎。

Kimi 的联网搜索官方文档目前注明：该服务正在更新，近期不建议使用，并请开发者关注后续文档更新。排查本示例前，请先查看该页面确认最新服务状态。

如果工具观察结果只有 search_id，例如 {"search_result": {"search_id": "..."}}，却没有实际搜索内容：

查看 Kimi 联网搜索文档，确认当前服务状态。
稍后重试；如果只需查看 ReAct 流程，可运行 python main.py --provider offline-demo，避免调用托管服务。
优先考虑外部工具/API 的可用性问题；仅凭这一响应，不能说明 Agent 循环或本地实现有误。

架构设计¶

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. 安装依赖¶

# 推荐在仓库根目录使用统一的第 1 章环境
uv sync --locked --extra ch1

# 切换目录前先激活环境：
# macOS/Linux：
source .venv/bin/activate
# Windows PowerShell：.venv\Scripts\Activate.ps1
# Windows cmd：.venv\Scripts\activate.bat

# 未安装 uv 时可用 pip 兜底：
# python -m pip install -e ".[ch1]"

# 进入本实验目录，后续命令都在这里运行
cd chapter1/web-search-agent

# 迁移期间仍支持单项目兼容路径：
# python -m 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）
[ ] 优化长对话的上下文管理

注意事项¶

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

使用建议¶

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

Notes / 说明¶

License: MIT.
许可证：MIT。
Author / 作者: AI Agent 实战训练营；version / 版本: 1.0.0.
Prefer --provider offline-demo first if you only want to see the ReAct shape without spending API quota.
若只想先看 ReAct 形态、不消耗配额，优先运行 --provider offline-demo。
Live search requires a Moonshot key; OpenRouter fallback has no $web_search.
真正联网搜索必须使用 Moonshot Key；OpenRouter 兜底没有 $web_search。