企业官网建设流程全解析

Agent Zero 的 search_engine 工具：实时网络搜索的查询规范与底层实现解析

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero

导读

search_engine是 Agent Zero AI framework 内置的实时数据检索工具，用于在对话中获取新闻、价格、版本发布等时效性强的网络信息。本文以 prompts/agent.system.tool.search_engine.md 为骨架，完整讲解该工具的调用协议、query 编写规范，并结合 tools/search_engine.py、helpers/searxng.py 及 Docker 部署配置，深入剖析其背后的 SearXNG 元搜索引擎链路。读完本文，你将掌握如何构造高召回率的搜索查询、理解工具返回结构与 Agent 循环的衔接方式，以及如何在 Docker 环境中配置搜索后端。

工具定位：什么场景下触发 search_engine

Agent Zero 的提示词体系要求 Agent 优先依赖自身记忆与上下文，但当任务需要当下正在发生的事实时，就必须调用搜索引擎兜底。search_engine的官方定义为：

find live news, prices, and other real-time web data

典型触发场景包括：

• 查询某软件的最新发布版本与更新日志（如 LiteLLM 最新 release）；
• 获取实时股价、汇率、商品价格；
• 检索当天的新闻事件、行业动态；
• 核对某个模型/版本号的最新状态。

与依赖固定知识库的记忆检索不同，search_engine返回的是搜索引擎实时抓取的网页结果，因此它在 Agent 需要"验证事实或补充时间敏感信息"时被调用，而不是在回答常识性、静态知识问题时被滥用。

调用协议：工具签名与返回结构

从提示词定义看，该工具的完整签名为：

Agent 以 JSON 形式发起工具调用，示例（来自原文档）：

{ "thoughts": ["I need current information rather than relying on memory."], "headline": "Searching the web", "tool_name": "search_engine", "tool_args": { "query": "LiteLLM latest release notes changelog" } }

调用时query为唯一必填参数。工具执行完成后，结果以"标题 + URL + 内容摘要"的三元组文本形式回传给 Agent，供其归纳、引用并组织成最终回答。该 JSON 调用格式与项目统一的工具协议一致，同样适用于 parallel 包装的多工具并发场景（tests/test_parallel_tool.py 中即以search_engine作为并行工具样本），并被 tests/test_tool_request_normalization.py 等测试用例验证为合法的工具名。

query 编写规范：从自然语言问句到关键词查询

原文档明确指出：search_engine接收的是关键词文本查询，而非自然语言问题。这是新手最容易犯的错误，也是影响召回质量的关键环节。

核心规则

1. 使用关键词、名称、精确短语、模型/版本号、日期和域名；
2. 不要写成自然语言问句或完整句子；
3. 省略填充词，如 "what"、"who"、"can you tell me"、"find information about"；
4. 使用 3～10 个高信号词；仅在确实能提升召回率时补充同义替代词。

正反例对照

反例之所以差，是因为搜索引擎会把 "What is"、"and what changed" 这类停用词和疑问结构当作噪音，导致匹配目标被稀释；而正例中的 "LiteLLM"（品牌名）、"latest release notes"（精确短语）、"changelog"（高信号词）组合在一起，能让下游搜索引擎精准命中官方发布页与更新日志。

实战构造步骤

• 先提取实体：产品名、人名、机构名、版本号、日期，如LiteLLM、v0.8.4、2026-09；
• 再补充限定词：release notes、changelog、pricing、news；
• 最后合并为 3～10 个词的紧凑查询，必要时用引号括起精确短语。

这条规范是 Agent 的"系统级行为约束"——它被写入 prompts/agent.system.tool.search_engine.md 后，会作为工具使用规则注入 Agent 上下文，确保每次调用都以搜索引擎友好的形式发出。

源码级实现：SearchEngine 工具的执行链路

工具的实际执行逻辑位于 tools/search_engine.py。核心类SearchEngine继承自helpers/tool.py中的Tool基类，执行流程如下：

SEARCH_ENGINE_RESULTS = 10 class SearchEngine(Tool): async def execute(self, query="", **kwargs): searxng_result = await self.searxng_search(query) await self.agent.handle_intervention(searxng_result) return Response(message=searxng_result, break_loop=False)

几个值得注意的实现细节：

• 异步执行：execute是async方法，搜索通过 aiohttp 异步 HTTP 调用完成，不阻塞 Agent 主循环；
• 结果上限：SEARCH_ENGINE_RESULTS = 10，格式化时截取前 10 条结果，避免上下文被过量网页摘要撑爆；
• 干预钩子：handle_intervention允许用户在搜索完成后、结果返回前介入（例如暂停 Agent 检查中间结果），这是 Agent Zero 的"人在环路"机制在工具层的体现；
• 返回结构：Response(message=..., break_loop=False)表明搜索结果不会中断 Agent 主循环，Agent 拿到结果后继续推理生成回答。

结果格式化逻辑同样在 tools/search_engine.py 中：

def format_result_searxng(self, result, source): if isinstance(result, Exception): handle_error(result) return f"{source} search failed: {str(result)}" outputs = [] for item in (result or {}).get("results", []): outputs.append(f"{item['title']}\n{item['url']}\n{item['content']}") return "\n\n".join(outputs[:SEARCH_ENGINE_RESULTS]).strip()

可以看到：异常会被handle_error捕获并以"search failed"文本返回；正常结果则从results列表中提取title、url、content三个字段，按"标题换行 URL 换行摘要、条目间空行分隔"的格式拼接——这正是原文档所说"returns urls, titles, and descriptions"的落地实现。

工具生命周期由基类 helpers/tool.py 托管：before_execution在调用前打印工具名与参数并写入日志，after_execution将结果经hist_add_tool_result写入对话历史，并更新工具日志。也就是说，每次search_engine调用都会在 Agent 的上下文与日志系统中留下完整轨迹，便于追溯与审计。

搜索后端：SearXNG 元搜索引擎与备用方案

search_engine的默认后端是SearXNG。网络层封装在 helpers/searxng.py：

URL = "http://localhost:55510/search" async def search(query: str): return await runtime.call_development_function(_search, query=query) async def _search(query: str): async with aiohttp.ClientSession() as session: async with session.post(URL, data={"q": query, "format": "json"}) as response: return await response.json()

实现要点：

• 通过runtime.call_development_function包装底层网络请求（便于开发态调试）；
• 向本机55510端口的/search端点发送 POST，表单字段为q（查询词）与format=json；
• 返回的 JSON 中results数组即结果列表。

从仓库结构看，项目还保留了另外两条搜索通道作为备选/参考实现：

• DuckDuckGo（helpers/duckduckgo_search.py）：基于duckduckgo_search.DDGS实现，支持region、safesearch、timelimit、max_results参数，文件头部保留了一段基于langchain_community的旧实现注释，可视为历史演进痕迹；
• Perplexity（helpers/perplexity_search.py）：调用 Perplexity 的在线模型（默认llama-3.1-sonar-large-128k-online），通过 OpenAI 兼容客户端请求，适用于需要"在线 LLM 直接给出带引用的回答"的场景。

三者职责不同：SearXNG 是当前工具默认使用的元搜索聚合器，DuckDuckGo/Perplexity 则是独立的能力模块，体现了项目在搜索通道上的可替换设计。

部署配置：Docker 环境下 SearXNG 的启动与调优

SearXNG 实例由 Docker 运行环境托管，相关配置集中在docker/run/fs下：

• 进程管理（docker/run/fs/etc/supervisor/conf.d/supervisord.conf）：supervisor 中定义了[program:run_searxng]程序块，以searxng用户身份执行启动脚本，并注入环境变量SEARXNG_SETTINGS_PATH=/etc/searxng/settings.yml；
• 启动脚本（docker/run/fs/exe/run_searxng.sh）：激活 SearXNG 的 Python 虚拟环境后运行searx/webapp.py；
• 核心配置（docker/run/fs/etc/searxng/settings.yml）：

use_default_settings: engines: remove: - radio browser - wikidata search: safe_search: 0 formats: - json server: secret_key: "dummy" port: 55510 limiter: false image_proxy: false

与search_engine直接相关的关键配置项包括：

• server.port: 55510：必须与 helpers/searxng.py 中硬编码的请求地址http://localhost:55510/search保持一致，否则工具无法连通后端；
• search.formats: [json]：仅开放 JSON 输出格式，正是工具所依赖的响应协议；
• search.safe_search: 0：关闭安全搜索过滤，避免过滤掉技术资料中的敏感关键词命中；
• use_default_settings.engines.remove：从默认引擎列表中移除radio browser与wikidata（注释说明 radio browser 在 x86 上会因gethostbyaddr崩溃而暂时禁用），体现项目对稳定性的取舍。

此外，docker-compose 与基础镜像中还包含 SearXNG 的安装步骤（docker/run/fs/ins/install_additional.sh 中注明"searxng - moved to base image"）。因此，若在非 Docker 环境或自定义部署中复现本工具，需自行保证一个监听在localhost:55510、支持q+format=jsonPOST 查询的 SearXNG 实例可用。

最佳实践与注意事项

综合提示词规范与源码实现，使用search_engine时建议遵循以下原则：

1. 只在需要实时数据时调用：版本发布、新闻、价格、动态事实用search_engine；静态知识优先走记忆与上下文，避免无谓的搜索开销；
2. 查询务必关键词化：3～10 个高信号词，宁可精确到版本号、日期、域名，也不要整句提问；
3. 善用精确短语与替代词："release notes"这类短语能显著提升命中率；只有首个查询召回不足时再补充同义词变体；
4. 信任返回结构的三个字段：url用于定位来源、title用于概括、content用于提取事实，Agent 应基于这三者组织回答并引用来源；
5. 知晓 10 条上限：结果被截断为前 10 条，若首屏无相关信息，应改写关键词重新搜索，而不是假设"网上没有"；
6. 后端依赖：搜索能力依赖 Docker 环境中由 supervisor 托管、监听 55510 端口的 SearXNG 服务；该服务不可用时，工具会返回 "search failed" 文本而非静默失败，Agent 可据此切换策略。

小结

search_engine是 Agent Zero 连接真实世界信息的窗口：提示词层定义了"关键词化查询"的行为规范，工具层实现了异步搜索、结果格式化与干预钩子，基础设施层则由 SearXNG 元搜索引擎承担实际检索。理解这三层结构，你就能正确使用该工具构造高召回查询，并能在自定义部署中定位搜索后端问题——从 query 规范、tools/search_engine.py 的实现细节，到 docker/run/fs/etc/searxng/settings.yml 的端口与格式配置，形成一条完整的可排查、可复用的知识链路。

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero