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_engineAgent Zero 的提示词体系要求 Agent 优先依赖自身记忆与上下文但当任务需要当下正在发生的事实时就必须调用搜索引擎兜底。search_engine的官方定义为find live news, prices, and other real-time web data典型触发场景包括查询某软件的最新发布版本与更新日志如 LiteLLM 最新 release获取实时股价、汇率、商品价格检索当天的新闻事件、行业动态核对某个模型/版本号的最新状态。与依赖固定知识库的记忆检索不同search_engine返回的是搜索引擎实时抓取的网页结果因此它在 Agent 需要验证事实或补充时间敏感信息时被调用而不是在回答常识性、静态知识问题时被滥用。调用协议工具签名与返回结构从提示词定义看该工具的完整签名为项目说明工具名search_engine参数query基于关键词的文本搜索查询返回urls、titles、descriptionsURL、标题、描述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接收的是关键词文本查询而非自然语言问题。这是新手最容易犯的错误也是影响召回质量的关键环节。核心规则使用关键词、名称、精确短语、模型/版本号、日期和域名不要写成自然语言问句或完整句子省略填充词如 what、who、can you tell me、find information about使用 310 个高信号词仅在确实能提升召回率时补充同义替代词。正反例对照类型写法错误What is the latest LiteLLM release and what changed?正确LiteLLM latest release notes changelog反例之所以差是因为搜索引擎会把 What is、and what changed 这类停用词和疑问结构当作噪音导致匹配目标被稀释而正例中的 LiteLLM品牌名、latest release notes精确短语、changelog高信号词组合在一起能让下游搜索引擎精准命中官方发布页与更新日志。实战构造步骤先提取实体产品名、人名、机构名、版本号、日期如LiteLLM、v0.8.4、2026-09再补充限定词release notes、changelog、pricing、news最后合并为 310 个词的紧凑查询必要时用引号括起精确短语。这条规范是 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(messagesearxng_result, break_loopFalse)几个值得注意的实现细节异步执行execute是async方法搜索通过 aiohttp 异步 HTTP 调用完成不阻塞 Agent 主循环结果上限SEARCH_ENGINE_RESULTS 10格式化时截取前 10 条结果避免上下文被过量网页摘要撑爆干预钩子handle_intervention允许用户在搜索完成后、结果返回前介入例如暂停 Agent 检查中间结果这是 Agent Zero 的人在环路机制在工具层的体现返回结构Response(message..., break_loopFalse)表明搜索结果不会中断 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.pyURL http://localhost:55510/search async def search(query: str): return await runtime.call_development_function(_search, queryquery) 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查询词与formatjson返回的 JSON 中results数组即结果列表。从仓库结构看项目还保留了另外两条搜索通道作为备选/参考实现DuckDuckGohelpers/duckduckgo_search.py基于duckduckgo_search.DDGS实现支持region、safesearch、timelimit、max_results参数文件头部保留了一段基于langchain_community的旧实现注释可视为历史演进痕迹Perplexityhelpers/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.confsupervisor 中定义了[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.ymluse_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、支持qformatjsonPOST 查询的 SearXNG 实例可用。最佳实践与注意事项综合提示词规范与源码实现使用search_engine时建议遵循以下原则只在需要实时数据时调用版本发布、新闻、价格、动态事实用search_engine静态知识优先走记忆与上下文避免无谓的搜索开销查询务必关键词化310 个高信号词宁可精确到版本号、日期、域名也不要整句提问善用精确短语与替代词release notes这类短语能显著提升命中率只有首个查询召回不足时再补充同义词变体信任返回结构的三个字段url用于定位来源、title用于概括、content用于提取事实Agent 应基于这三者组织回答并引用来源知晓 10 条上限结果被截断为前 10 条若首屏无相关信息应改写关键词重新搜索而不是假设网上没有后端依赖搜索能力依赖 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Agent Zero 的 search_engine 工具：实时网络搜索的查询规范与底层实现解析
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_engineAgent Zero 的提示词体系要求 Agent 优先依赖自身记忆与上下文但当任务需要当下正在发生的事实时就必须调用搜索引擎兜底。search_engine的官方定义为find live news, prices, and other real-time web data典型触发场景包括查询某软件的最新发布版本与更新日志如 LiteLLM 最新 release获取实时股价、汇率、商品价格检索当天的新闻事件、行业动态核对某个模型/版本号的最新状态。与依赖固定知识库的记忆检索不同search_engine返回的是搜索引擎实时抓取的网页结果因此它在 Agent 需要验证事实或补充时间敏感信息时被调用而不是在回答常识性、静态知识问题时被滥用。调用协议工具签名与返回结构从提示词定义看该工具的完整签名为项目说明工具名search_engine参数query基于关键词的文本搜索查询返回urls、titles、descriptionsURL、标题、描述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接收的是关键词文本查询而非自然语言问题。这是新手最容易犯的错误也是影响召回质量的关键环节。核心规则使用关键词、名称、精确短语、模型/版本号、日期和域名不要写成自然语言问句或完整句子省略填充词如 what、who、can you tell me、find information about使用 310 个高信号词仅在确实能提升召回率时补充同义替代词。正反例对照类型写法错误What is the latest LiteLLM release and what changed?正确LiteLLM latest release notes changelog反例之所以差是因为搜索引擎会把 What is、and what changed 这类停用词和疑问结构当作噪音导致匹配目标被稀释而正例中的 LiteLLM品牌名、latest release notes精确短语、changelog高信号词组合在一起能让下游搜索引擎精准命中官方发布页与更新日志。实战构造步骤先提取实体产品名、人名、机构名、版本号、日期如LiteLLM、v0.8.4、2026-09再补充限定词release notes、changelog、pricing、news最后合并为 310 个词的紧凑查询必要时用引号括起精确短语。这条规范是 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(messagesearxng_result, break_loopFalse)几个值得注意的实现细节异步执行execute是async方法搜索通过 aiohttp 异步 HTTP 调用完成不阻塞 Agent 主循环结果上限SEARCH_ENGINE_RESULTS 10格式化时截取前 10 条结果避免上下文被过量网页摘要撑爆干预钩子handle_intervention允许用户在搜索完成后、结果返回前介入例如暂停 Agent 检查中间结果这是 Agent Zero 的人在环路机制在工具层的体现返回结构Response(message..., break_loopFalse)表明搜索结果不会中断 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.pyURL http://localhost:55510/search async def search(query: str): return await runtime.call_development_function(_search, queryquery) 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查询词与formatjson返回的 JSON 中results数组即结果列表。从仓库结构看项目还保留了另外两条搜索通道作为备选/参考实现DuckDuckGohelpers/duckduckgo_search.py基于duckduckgo_search.DDGS实现支持region、safesearch、timelimit、max_results参数文件头部保留了一段基于langchain_community的旧实现注释可视为历史演进痕迹Perplexityhelpers/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.confsupervisor 中定义了[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.ymluse_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、支持qformatjsonPOST 查询的 SearXNG 实例可用。最佳实践与注意事项综合提示词规范与源码实现使用search_engine时建议遵循以下原则只在需要实时数据时调用版本发布、新闻、价格、动态事实用search_engine静态知识优先走记忆与上下文避免无谓的搜索开销查询务必关键词化310 个高信号词宁可精确到版本号、日期、域名也不要整句提问善用精确短语与替代词release notes这类短语能显著提升命中率只有首个查询召回不足时再补充同义词变体信任返回结构的三个字段url用于定位来源、title用于概括、content用于提取事实Agent 应基于这三者组织回答并引用来源知晓 10 条上限结果被截断为前 10 条若首屏无相关信息应改写关键词重新搜索而不是假设网上没有后端依赖搜索能力依赖 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
