企业官网建设流程全解析

最近一年里，跟 Agent 打交道多了，我最大的一个感受是：模型本身的智商当然重要，但真正决定一个 Agent 能干多少活的，往往是它手里有没有趁手的家伙。很多同学搭 Agent 时，把精力全扑在提示词和模型选型上，结果一跑真实任务就露馅——要么回答不了实时信息，要么算不对数，要么扔过来一个 CSV 让它分析，它只能干瞪眼。说白了，缺的就是“工具箱”。这篇我就想认真拆一拆 Agent 最常用的三件套：SearxNG、WolframAlpha 和代码解释器，讲讲它们各自解决什么问题、怎么接进来、以及我实际用下来踩过的那些坑。不管你是刚接触 Agent 开发，还是已经在做多智能体系统，这篇应该都能给你一些可以照抄的参考。

1. 为什么 Agent 需要工具箱：从“嘴强王者”到“动手干活”

1.1 大模型的三块短板

咱们先捋清楚一个前提：为什么 Agent 不能只靠模型本身活着？我见过不少人有个误解，觉得大模型什么都知道。实际上，把模型当成一个“纯靠记忆说话的人”更准确，它有三块特别明显的短板。

第一块是实时信息缺失。模型训练有个截止时间，之后发生的事它一概不知。比如你问它“今天热搜是什么”或者“某个包的最新版本号是多少”，它只能靠猜，甚至一本正经地编一个不存在的版本号给你。第二块是精确计算能力不足。语言模型本质上是在预测下一个词，你让它算 123456789 乘以 987654321，它大概率给你一个近似值，而不是精确答案。至于微积分、矩阵运算、解方程这种符号推演，更是容易翻车。第三块是无法操作外部环境。模型输出的只是文本，它没法帮你查数据库、读文件、执行一段 Python 脚本、调用一个 API。如果需要这些能力，就必须有“手”和“眼睛”伸出去，把结果拿回来喂给它。

这其实就是 Agent 这个词和普通 Chatbot 的根本区别。普通对话机器人是“你说一句，它回一句”，而 Agent 的核心在于自主决策、调用工具、完成任务。工具不是锦上添花，是必需品。没有工具链的 Agent，就像一个只有嘴、没有手的员工，能侃侃而谈，但真要干活就歇菜。

1.2 工具调用的核心机制：Function Calling

你可能听说过一个词叫 Function Calling（也有人叫 Tool Calling / Tool Use）。它是目前把工具接到 Agent 上的主流方式。原理不复杂：你在给模型的请求里，额外声明一批“可用的函数”，每个函数都有名字、描述、参数列表。模型在理解用户需求后，不是直接输出最终答案，而是先输出一个结构化的“调用意图”，比如“我需要调用 search 这个函数，参数是 xxx”。

然后你作为开发者，在自己的代码里真正执行这个函数（比如真的去搜索，或者真的去跑一段 Python），拿到结果后再把结果“回填”给模型。模型结合函数返回的真实结果，生成给用户的最终答复。你可以把整个循环理解为：思考 → 选工具 → 执行 → 再看结果 → 再思考。这也是目前 Agent 架构里最核心、最常用的一套交互逻辑。

在这个逻辑里，工具自身的能力边界、返回数据的质量，直接决定了 Agent 的最终表现。所以你会看到，真正追求落地效果的人，很少用那种“一键封装好的全能 Agent 框架”，而是会自己仔细挑选和打磨每一个工具。

1.3 三件套的分工定位

我这次聊的三件套，刚好覆盖了 Agent 最典型的三大类需求：信息检索、精确计算、代码执行。

SearxNG 解决的是“实时信息从哪来”的问题。它是一个自托管的元搜索引擎，聚合了 Google、Bing 等多个上游搜索引擎的结果，并且有干净的 JSON API，特别适合让 Agent 去搜索网页、新闻、文档。你可以把它理解为给 Agent 装了一扇通向实时互联网的窗户。

WolframAlpha 解决的是“精确知识计算”的问题。它是一个计算知识引擎，擅长数学计算、单位换算、物理化学常量查询、数据对比等。你可以把它理解为一个“理科大脑”，专门补足语言模型在符号推理和精确计算上的短板。

代码解释器（Code Interpreter / Code Sandbox）解决的是“真正动手处理数据”的问题。它提供一个隔离的 Python 执行环境，Agent 可以写代码计算、分析、绘图、处理文件。它补足的是 Agent 的“动手能力”，相当于一个功能不限的计算机实验室。

这三个工具加在一起，Agent 基本就具备了一个完整“初级研究员”的能力：能查资料、能算数、能写代码做验证。下面我挨个展开。

2. SearxNG：自托管元搜索引擎，给 Agent 装上一双“眼睛”

2.1 为什么选 SearxNG，而不是直接调搜索引擎 API

做 Agent 信息检索时，你首先会面对一个选择：是直接用某家搜索服务的官方 API，还是自己搭一个聚合搜索？

直接用官方 API 确实省事，但它有几个现实问题。第一是成本，商业搜索 API 按千次请求计费，开发阶段频繁调试会心疼。第二是配额，很多免费额度每天只有几十次到几百次，Agent 一旦跑起来，一次多轮对话可能就要发起好多次搜索，配额烧得飞快。第三是灵活度，你想控制搜索地域、语言、时间范围、结果数量时，官方 API 的参数往往有限。

SearxNG 的好处恰好在于：它是开源的、自托管的、无请求费用。你把它跑在一台低配的小服务器上，它就变成一个完全属于你自己的搜索入口，代理所有上游搜索引擎的请求，最后汇总去重返回结果。对 Agent 来说，这意味着一个稳定可控、成本几乎为零的检索接口。

另外还有一层隐私考虑。SearxNG 默认不保存用户查询记录，对于处理敏感数据或企业内部信息的 Agent 来说，这比把查询直接发给第三方搜索服务更让人放心。虽然在 Agent 场景下隐私权重没那么高，但“数据不出自家服务器”这一点，在不少企业项目里是硬需求。

2.2 快速部署：Docker 一键启动

SearxNG 部署非常简单，官方提供了 Docker 镜像，这也是我最推荐的方式。你不用关心 Python 依赖、系统配置这些破事，一条命令就能跑起来。基本步骤如下：

# 拉取镜像 docker pull searxng/searxng # 创建数据目录，存放配置文件 mkdir -p /opt/searxng cd /opt/searxng # 生成基础配置，或用官方提供的 searxng.conf # 大致命令路径如下，直接使用官方 git 仓库的配置文件也行

如果你不想手工写配置，我直接给你一个最小可用的searxng.conf参考片段：

use_default_settings: true server: secret_key: "换成你自己的随机字符串" limiter: false image_proxy: true search: safe_search: 0 autocomplete: "google" default_lang: "zh-CN" formats: - html - json search_engines: - name: google engine: google shortcut: g disabled: false - name: bing engine: bing shortcut: b disabled: false

配置文件里重点说几个参数：

• secret_key：必填，用于会话签名，你可以用openssl rand -hex 32生成一个。
• limiter: false：开发调试时建议先关掉限流，不然高频请求会被拦截，后面再按需打开。
• formats里必须包含json，这是 Agent 调用时必须的接口格式。
• search_engines里你可以只保留一两个常用的引擎，引擎太多反而会导致每次搜索都要等最慢的那个，整体延迟变高。

改完配置，启动容器：

docker run -d \ --name searxng \ --restart=unless-stopped \ -p 8888:8080 \ -v /opt/searxng:/etc/searxng \ searxng/searxng

注意我把容器内部的 8080 端口映射到了宿主的 8888 端口，这样只要访问http://你的服务器IP:8888就能打开搜索页面。测试一下页面能开、能搜出结果，部署这步就算过了。如果你对 Docker 不熟悉，直接把它当成“一个隔离的小环境”就好，所有依赖都打包在里面，不影响系统其他部分，非常干净。

2.3 JSON 接口：Agent 最关心的调用方式

Searxng 的页面模式是给人用的，而 Agent 要用的是它的 JSON 接口。请求方式很简单，就是对搜索端点加一个format=json参数：

curl "http://localhost:8888/search?q=LangChain+agent+tool+call&format=json&language=zh-CN"

返回的 JSON 结构里，最核心的字段是results数组，每个元素包含title、url、content这些字段。content一般是搜索结果摘要，Agent 主要靠它快速判断这条结果值不值得点开。另外还有infoboxes（知识卡片）、suggestions（搜索建议），这些在特定场景下也很有用。

我在代码里给 Agent 封装搜索函数时，通常会做一层轻量处理：把结果截断到前五条，每条只保留标题、链接和摘要的前 200 个字符。为什么要截断？因为大模型的上下文窗口虽然越来越大，但塞进去太多垃圾信息会稀释注意力，反而让回答质量下降。给模型“够用”的信息量比“海量”信息量更明智。

import requests def searxng_search(query: str, max_results: int = 5) -> list[dict]: params = { "q": query, "format": "json", "safesearch": "0", } resp = requests.get("http://localhost:8888/search", params=params, timeout=15) resp.raise_for_status() results = resp.json().get("results", []) # 只保留关键字段，截断长文本 cleaned = [] for item in results[:max_results]: cleaned.append({ "title": item.get("title", ""), "url": item.get("url", ""), "content": item.get("content", "")[:200], }) return cleaned

2.4 实例维护与常见注意点

SearxNG 最大的好处是免费，但它并不是零维护。我跑了几个月，总结出三个需要注意的地方。

第一是上游引擎的屏蔽问题。某些搜索服务对数据中心 IP 不太友好，会弹验证码或者直接拒绝流量，表现就是 SearxNG 页面能开，但搜索一直转圈超时。解决办法是换一个对机房 IP 友好些的引擎配置，或者调整请求间隔。没有万能的引擎组合，只能实测调整。

第二是请求频率。虽然 SearxNG 没有费用，但你架不住它背后的上游引擎有风控。如果你的 Agent 同时发起太多并发搜索，即使 SearxNG 收到请求，上游的 Google 或 Bing 也会开始频繁报错。我后面会把工具调用改成串行或加一个简单的令牌桶限速，效果会好很多。

第三是结果质量参差。元搜索聚合了多个来源，结果里偶尔会混入广告、低质内容。如果 Agent 对内容准确性要求高，我建议在系统提示词里写一句“优先参考权威域名来源”，同时在上层再加一道内容校验，比如过滤掉明显是营销推广的标题关键词。

注意：SearxNG 默认返回的content字段是摘要截断，不要把它当作完整网页内容。Agent 如果需要深入阅读某一篇网页，后面还得接一个抓取正文的工具（比如某种 HTML 解析器），这是另一个话题，但是信息链路里很重要的一环。

3. WolframAlpha：计算知识引擎，补上 Agent 的“理科大脑”

3.1 它能做什么：不只算数，更像一本可计算的百科全书

WolframAlpha 从 2009 年上线到现在，定位一直很特别。它既不是搜索引擎，也不是普通的计算器，而是一个“计算知识引擎”。你输入一个自然语言问题，它先在语料库里理解问题意图，再做查询和计算，最后返回结构化结果。

对 Agent 而言，它补的是语言模型最难啃的一块：需要精确计算和权威知识的场景。举个例子：

• 数学计算：integrate x^2 * sin(x)这种符号积分，模型可能给错，WolframAlpha 直接给步骤和结果。
• 单位换算：120 miles in kilometers，它精确返回 193.121 km。
• 物理常量：speed of light in m/s，返回精确数值和量纲。
• 日期计算：days between 2023-01-01 and 2024-06-15，精确到天。
• 事实对比：population of China vs India，拉一整套逐年数据出来。

我自己的体会是，WolframAlpha 不是用来做开放域问答的，它的知识覆盖偏向数学、物理、化学、统计、地理、金融等“可计算、可验证”的领域。如果你让 Agent 针对“今天热搜”这种开放问题去问它，那纯属用错工具。但一旦遇到计算、验证、单位、常量这类需求，它几乎没有替代品。

3.2 API 接入：申请密钥与发起请求

WolframAlpha 接入要在它的开发者平台注册账号，然后申请一个 App ID。免费额度有限（每月 2000 次左右，准确数字按官方最新政策），个人开发和原型测试基本够用。如果你要商用或者跑大规模 Agent，就得升级付费计划。

拿到 App ID 后，调用来之也很简单。它有两种 API：Simple API（返回图像或 JSON）、Full Results API（返回结构化 XML）。对 Agent 来说，用 Full Results API 拿结构化数据更合适，因为解析出来的结果可以直接作为上下文交给模型。

下面是 Python 示例：

import requests import xml.etree.ElementTree as ET APP_ID = "你的AppID" def wolfram_query(query: str) -> str: params = { "appid": APP_ID, "input": query, "format": "plaintext", "output": "json", # 新版API支持JSON输出 } resp = requests.get( "https://api.wolframalpha.com/v2/query", params=params, timeout=20, ) resp.raise_for_status() data = resp.json() # 抽取所有 plaintext 结果拼成一段文本 texts = [] for pod in data.get("queryresult", {}).get("pods", []): for sub in pod.get("subpods", []): if "plaintext" in sub and sub["plaintext"]: texts.append(sub["plaintext"]) return "\n".join(texts)

上面的代码是最小可用版。实际项目中你还会想保留 pod 的标题字段（比如 “Input interpretation” 和 “Result”），因为模型看这些标签更容易理解结果含义。整体思路就是：把 WolframAlpha 返回的结构化结果“拍平”成纯文本，再喂给模型。

3.3 返回结果的结构：学会读“pods”

要用好 WolframAlpha API，必须知道它返回的数据结构。每个查询结果由若干pods（可以理解为“面板”）组成，每个 pod 有标题（title）和若干subpods。常见的 pod 有：

• Input interpretation：你对问题的解读，可以看作对查询语义的确认。
• Result：最终计算结果，这是最核心的。
• Step-by-step solution：解题步骤，需要额外参数podstate或替换stepbystepsolution=true才会返回。
• Plots：图像，Agent 一般不直接看图像，但可以获取图表的元信息。
• Alternate form/Decimal approximation：不同形式的结果。

我第一次对接时犯过一个蠢错：把 API 返回的整个 JSON 直接塞给模型。结果导致模型被无用的图像 URL 和 XML 元数据干扰，回答反而变慢变差。后来我学乖了，只做一层过滤，把每个 pod 的title和plaintext字段拎出来拼成简短文本，效果立刻提升。这也是我想反复强调的一点：工具返回值要“精加工”再交给模型，而不是把原生响应怼过去。

3.4 什么时候该切到 WolframAlpha：工具选择与路由策略

Agent 不是遇到所有问题都应该调用 WolframAlpha，调用得太多反而会拖慢响应。我常用的做法是在系统提示词里给模型写清楚“什么时候用这个工具”，比如：

当用户的问题涉及精确数学计算、单位换算、科学常量、日期计算、统计比较时，优先调用 wolfram_alpha 工具。如果只是开放域信息查询，不要调用它。

但完全靠模型自觉选工具并不总是可靠，它在模糊问题下经常会选错。所以我在上层加了一道轻量规则：先做一次关键词/模式匹配，发现问题里包含“计算”“多少公里等于”“怎么积分”“太阳质量”之类的模式，就直接强制走 WolframAlpha，不走模型决策。这是一种非常朴素的“意图路由”，但对提准确率很有效。

我还想提一个注意点：WolframAlpha 并不擅长中文自然语言。它理解英文查询的效果远好于中文。所以我在封装工具时，会在调用前加一步“把用户问题翻译成英文”的处理，最简单的做法就是用同一个大模型顺手翻译一下，或者在系统提示词里要求“不要翻译”。别小看这个小细节，它直接影响命中率，实测能差出一大截。

4. 代码解释器：让 Agent 真正“动手算”，而不只是“开口说”

4.1 代码解释器到底解决什么问题

搜索和计算能解决很多问题，但还有一大类需求它们搞不定：“处理你给我的数据”。比如用户上传一个 CSV 文件说“帮我统计每个月的销售额并画出趋势图”，或者用户问“请用蒙特卡洛方法模拟一下，中奖概率是 10% 的情况下连买 100 次至少中一次的概率是多少”。这种问题要真正给出可信答案，唯一的路是真正去执行一段代码。

代码解释器本质是一个受控的 Python 运行环境。Agent 自己写 Python 代码，然后丢进这个环境里执行，再把 stdout 的结果或生成的图片文件拿回来。说白了，Agent 不在“脑内”推理了，而是“脚踏实地”地写代码干活，于是几乎所有数据任务它都能化为可计算的程序问题。

这也是“嘴强王者”和“动手干事”的一道重要分水岭。没有代码解释器的 Agent，遇到数值模拟只能硬编一个公式让模型“口算”；有了代码解释器，它可以写 20 行脚本跑一万次模拟，直接拿到精确分布。

4.2 三种集成方式：本地执行、容器执行、托管沙箱

实现代码解释器有几种路线，从简单到靠谱，我依次说下。

方式一：本地exec/subprocess执行

这是最快上手的方案，直接把模型生成的 Python 代码在当前进程里跑。开发调试时很方便，模型写一个print(2+2)，你用exec一执行就能拿到结果。但生产环境千万别这么干。原因很直接：大模型生成的代码是不可信的。它可能无意中写一个死循环，把你的服务 CPU 跑满；更严重的，它可能读到环境变量、删文件。本地执行等于把你的服务器完全暴露给模型。只建议在完全隔离的本地开发环境里玩玩。

方式二：容器执行（Docker 单次沙箱）

这是我最推荐的生产级做法。每调用一次代码解释器，就启动一个一次性 Docker 容器，在容器里执行代码，跑完即销毁。因为容器是隔离的，模型代码无法触碰宿主机文件，最多影响那个临时容器。实现方式可以用 Docker SDK。

import docker import uuid client = docker.from_env() def run_code(code: str, timeout: int = 30) -> str: container_name = f"sandbox-{uuid.uuid4().hex[:8]}" try: container = client.containers.run( "python:3.11-slim", command=["python", "-c", code], detach=True, mem_limit="512m", pids_limit=100, network_mode="none", # 默认不给网络，更安全 name=container_name, ) result = container.wait(timeout=timeout) logs = container.logs().decode("utf-8") return logs finally: try: client.containers.get(container_name).remove(force=True) except Exception: pass

注意几个细节：network_mode="none"断掉容器网络，防止模型代码访问外部；mem_limit和pids_limit限制资源，防死循环和内存爆炸；timeout超时报错兜底，防挂起。这套方案每次执行约增加 1-2 秒启动开销，但对稳定性来说是值得的。

方式三：托管沙箱服务

如果你不想维护 Docker，可以直接用云厂商的沙箱 API。比如某些模型厂商自带的代码解释器功能，上传代码执行后返回文本和文件。好处是天然隔离、不用运维；坏处是数据要出网，且计费方式按调用次数或时长。对于内部数据敏感的 Agent，还是自托管更放心。

4.3 给模型定义代码解释器工具时的“说明书”

模型写代码的技能再强，也需要你明确告诉它能做什么、不能做什么、期望返回什么。工具描述写得越具体，模型写出的代码越规范，返工的概率越低。我的代码解释器工具描述通常会这么写：

功能：执行 Python 代码并返回标准输出文本。 限制：当前无网络连接；只能使用预先安装的标准库及 numpy、pandas、matplotlib；不要尝试读取本地文件；代码必须能在 30 秒内运行完成。 输出格式：返回运行结果的 stdout 内容。

为什么强调“只能使用预装库”？因为沙箱环境下没有网，pip install是不度发挥作用的。你不可能让模型每次现装第三方包。我一般会在镜像里预装numpy、pandas、matplotlib、scipy，这四件套覆盖了绝大多数数据分析场景。如果遇到不支持的库，模型也会很自然地调整方案，改用标准库实现。

4.4 典型实战：用代码解释器画图并返回给用户

多数框架下，代码解释器不仅能返回文本，还能返回图片。比如用户说“帮我生成一条正弦曲线图”，Agent 的完整流程是：

1. 用户请求 → 模型决策要调用代码解释器
2. 模型生成代码：用 matplotlib 绘制正弦曲线，保存为 PNG
3. 沙箱执行代码 → 生成文件
4. 工具返回文件路径 → 模型引用“图片已经生成”
5. 前端展示图片，Agent 同时给出一句简短介绍

我在封装时会让容器把工作目录挂载到宿主机的共享目录，或者用docker cp把生成产物导出，再让主服务读取返回给用户。整个过程跑通后，Agent 就具备了真正的“可视化输出”能力，这对数据分析类 Agent 来说是刚需。

注意：代码解释器不是越复杂越好。有些开发者喜欢给模型塞一堆工具让模型自己挑，但我后来发现，工具数量太多会让模型决策变慢、变混乱。工具描述的简洁性和职责单一性，比工具数量重要得多。

5. 三个工具怎么协同：从一个实际任务看 Agent 的工具编排

5.1 一个综合示例：三件套接力完成数据分析任务

工具单个都好说，真正见功夫的是怎么让它们配合起来。我带大家过一遍实际场景，假设用户问：

“请帮我查一下过去一年某大宗商品的价格走势数据，然后计算平均价格和最大回撤，并画一张价格曲线图。”

这个需求里其实包含三类子任务：实时信息获取（查价格数据）、精确计算（平均值和最大回撤）、代码执行（画图）。一个合格的 Agent 工作流应该是：

用户发起请求 → 决策：调用 SearxNG 搜索“XX商品 价格走势 历史价格数据” → 拿到若干网页结果，Agent 筛选最可信的数据来源 → 决策：调用代码解释器 → 代码解释器读取数据（比如 CSV 或 API 数据），计算均值、最大回撤，绘图 → 生成 PNG 图片 → 决策：如果需要验证某个数字的正确性或补充权威知识，调用 WolframAlpha → 返回最终答案 + 图片

这不是我拍脑袋设计的，而是真实跑通过的一条链路。每个工具只负责自己最擅长的一段，Agent 像流水线一样把结果串起来。

5.2 工具编排的决策逻辑：什么时候用哪个

很多 Agent 框架用模型自动决策，但纯靠模型“自由发挥”在一个复杂任务里经常跑偏。我更倾向于一个混合策略：

• 强制路由 + 模型决策结合。能被规则提前判断的需求（比如“计算”“搜索”“绘图”关键词），直接走固定工具；模糊需求再交给模型判断。
• 结果校验。工具返回结果后，不是立刻给用户，而是先让模型做一轮“结果与问题是否匹配”的检查。如果搜索不到有效内容，模型应该主动承认“没有找到，换一种方式”，而不是硬编答案。

这里我想说一个很多教程不会提的细节：工具调用需要“重试策略”。搜索可能失败、WolframAlpha 可能超时、代码解释器容器可能起不来。Agent 至少要具备“失败后换个工具再试一次”的能力。我见过一个很典型的翻车案例：Agent 调 WolframAlpha 计算一个积分失败，就直接延用模型自己的“口算结果”回答了，结果还是错的。正确做法是失败后先用代码解释器用 SymPy 算一遍。你看，工具多了还有一个好处——可以互相兜底。

5.3 系统提示词里如何描述工具

工具描述写到什么程度，直接决定模型用得顺不顺手。我常用的格式如下：

你有以下工具可用： 1. searxng_search(query: str): 实时网络搜索，适合获取最新信息、查找资料、寻找数据来源。返回标题、链接和摘要。 2. wolfram_alpha(query: str): 计算知识引擎，适合数学计算、单位换算、科学常量查询、日期计算。查询请用英文表达。 3. code_interpreter(code: str): 执行 Python 代码，适合数据计算、数据处理、绘图、模拟。环境中预装有 numpy/pandas/matplotlib/scipy，无网络。 请根据用户需求选择合适的工具。一次只调用一个工具，拿到结果后再决定下一步。

最后那句“一次只调用一个工具”很重要。虽然现在很多框架支持并行工具调用，但两个工具同时跑，如果它们有依赖关系（比如代码解释器需要搜索到的数据），并行反而会乱。先串行、再优化，这是稳妥的路径。

5.4 模型与工具之间的“心跳”：上下文记忆管理

工具调用会带来一个容易忽略的问题：上下文膨胀。每次搜索返回 5 条结果，每条 200 字，看起来不多，但多轮对话里如果每次都塞原始结果，上下文会越滚越大，最后模型连自己刚说过什么都记不清了。

我处理的办法是给工具返回值设置“有效期”。比如搜索结果的引用只在当前这一轮对话生效，下一轮用户没问相关内容就直接丢弃；代码解释器的输出如果只是数值，就只保留最终结论和关键数字，不保留完整日志。这本质上是一种轻量的记忆管理，但做好它，Agent 的多轮稳定性会显著提升。

提示：工具返回内容进上下文前，先让一个小的“压缩器”模型（或者同一个模型）把结果提炼成三句话以内。这是对抗上下文膨胀非常有效的手段。

6. 实测中踩过的坑与排查技巧实录

6.1 SearxNG：请求超时与结果为空

现象：Agent 偶尔报错“搜索超时”或者“搜索无结果”，但用浏览器手动打开 SearxNG 页面又能搜出来。

排查思路：

• 先确认 SearxNG 服务本身负载，docker stats看 CPU 是不是被打满了。
• 再检查是否有限流，limiter: true时高并发请求会被拦，报错码一般是 429。
• 最后看上游引擎是否被墙或触发验证码，换一个引擎试试。

经验教训：SearxNG 的搜索质量和你选的引擎高度相关。只开一个 Google 有时不稳定，我后来开了三个引擎做冗余，某些引擎失败时会自动 failover，整体可用性从 80% 提到 99% 以上。

6.2 WolframAlpha：查询未命中与结果解析失败

现象：模型把查询问题翻译成英文后，WolframAlpha 依然返回 “Wolfram|Alpha did not understand your input”。

排查思路：

• 检查查询语句是不是太口语化。WolframAlpha 对自然语言的理解是有边界的，calculate what is the meaning of life这种超出范围就要换问法。
• 参考答案里的Input interpretationpod，看看它把问题理解成什么了，再换关键词重新组织语句。
• 避免一次问多个子问题。把“计算 A 并比较 B”拆成两次查询，命中率会提高很多。

解析失败也很常见，我遇到过 WolframAlpha 返回 JSON 里pods为空的场景。这时候可以在代码里加一个判断：如果data["queryresult"]["success"]为false，直接向前端返回“该问题超出计算引擎范围”，避免模型拿空结果硬编。

6.3 代码解释器：环境缺失与资源耗尽

现象：模型生成的代码引用了statsmodels，但沙箱里没装；或者代码里有个死循环，把容器的 CPU 打满，导致整个 Agent 卡住。

处理办法：

• 预先在python:3.11-slim镜像里装好常用库，制作成自定义镜像，避免运行时依赖。
• pids_limit和mem_limit一定要设置，这是防死循环和内存溢出的关键。
• 给超时设置兜底，比如container.wait(timeout=30)超时后直接 kill，并返回“代码执行超时”给模型，让模型自己想办法改代码。

这里有一个容易被忽略的坑：模型生成的代码不会自己处理异常。比如 numpy 数组除零会产生警告而不是报错，但结果可能是 inf。如果你直接把这个结果当有效输出，Agent 就会给用户一个错误的结论。我后来会在系统提示词里加一句：“你的代码必须对边界情况做防御性检查”，并且在上层工具里对结果做一轮 NaN/inf 检测。

6.4 工具之间的“互相打架”

现象：Agent 先搜了资料，又调 WolframAlpha 算了一个不相关的数，最后代码解释器又跑了一堆无关代码，整个回答又慢又乱。

原因多半是工具描述不够清晰，模型不知道该在什么时候停下来。我最终的优化方案是：

• 把工具描述里的“使用条件”写得更明确。
• 在系统提示词里增加“完成标志”：当且仅当所有子问题得到回答，或用户不再需要进一步工具调用时，停止调用工具并给出最终答案。
• 如果框架支持，设置最大工具调用次数（比如 5 次），超限强制结束，避免无限循环。

我还留意到，有些开源的 Agent 框架会默认给模型“自动摘要”的权限，模型为了完成任务自己调了一个摘要工具，反而把上下文内容缩短了，弄丢了关键信息。这种“工具自杀”式调用，排查起来很费劲，唯一的方法就是每次工具调用前后打印日志，盯紧上下文变化。

6.5 一张实用速查表

为了方便你排查问题，我整理了一张常用排查表：

这张表的价值在于：当 Agent 表现不稳定时，先别怀疑大模型能力，先查工具层。很多“模型变笨了”的错觉，其实是工具链出问题了，比如一直搜到没用的结果、计算公式被错误翻译、代码环境缺库。把工具链调稳，模型的表现自然就上来了。

我个人在实际操作中的体会是：Agent 开发到后期，大部分时间不是在调模型，而是在调工具。Search 结果的质量、WolframAlpha 的查询措辞、沙箱环境的依赖版本，任何一个环节掉链子，最终都会在用户那边放大成一个“AI 不靠谱”的整体印象。所以别嫌这些基础工具“太低级”，越是底层的东西，越值得反复打磨。

最后再分享一个小技巧：你可以给每个工具加上“返回状态码”字段，比如搜索无结果返回 404，计算未命中返回 422，代码超时返回 508。这样模型看到状态码就能立刻知道发生了什么，比自己从内容里猜准确得多，也能减少一层提示词的负担。工具反馈越结构化，Agent 的决策就越稳定。如果你正在搭自己的 Agent 工具箱，不妨把这个细节直接加进去，实测下来会很省心。