AI智能体在执行任务时依赖工具调用与外部世界交互，比如查询数据库、请求第三方API、执行搜索等。当工具调用返回空结果时，智能体的推理链路就会中断或者产生幻觉输出，这是构建Agent系统时最常见也最棘手的故障之一。空结果问题的麻烦之处在于它没有报错信息，函数正常返回、流程正常走完，唯独结果为空，让人无从下手。本文将从工具定义、参数传递、响应解析、日志埋点四个层面，系统地讲解排查这类问题的思路和方法。
一、先确认空结果的类型：None、空字符串还是空列表
排查的第一步是搞清楚空结果到底是什么形态。很多开发者把所有空输出笼统地归结为返回空，但实际上None、空字符串、空列表、空字典背后的原因完全不同。None通常意味着函数内部有分支没走到返回语句，或者异常被静默吞掉了；空字符串往往出现在字符串拼接逻辑中某个变量为空；空列表则更多是过滤条件过严或数据源本身没匹配到数据。
建议在工具函数入口和出口分别加上类型断言与日志输出，先把空结果的具体形态固定下来。示例如下：
def search_knowledge_base(query: str) -> list:
import logging
logging.info(f"[tool-entry] query={query!r}, type={type(query)}")
try:
results = db_client.query(query)
except Exception as e:
logging.error(f"[tool-error] {e}")
return [] # 这里就是空列表的常见来源之一：异常被静默处理
logging.info(f"[tool-exit] len={len(results) if results else 'None'}, "
f"type={type(results)}")
return results or []
上面这段代码暴露了一个典型问题：except块中直接返回了空列表，把真实的异常信息吞掉了。这种写法在智能体工具函数里非常普遍，表面上是优雅降级，实际上是调试的最大障碍。正确的做法是把异常记录到日志并打上标记，必要时抛出自定义异常让Agent框架感知到调用失败，从而触发重试或换路逻辑。
二、检查大模型生成的参数是否合法
Agent工具调用的参数由大模型生成，而模型输出的参数经常不符合预期。最典型的几种情况是：参数值为空字符串、参数类型不对（模型给了字符串而函数需要整数）、参数名拼写错误、或者模型把多个参数合并成了一个长文本。这些情况下，工具函数本身没有bug，但拿到的输入就是空的，查询自然返回空结果。
排查方法是把模型的原始输出完整记录下来，而不是只记录函数的返回值。以下是一个带参数校验的工具封装示例：
from pydantic import BaseModel, field_validator
class SearchArgs(BaseModel):
query: str
top_k: int = 5
@field_validator("query")
@classmethod
def query_not_empty(cls, v):
if not v or not v.strip():
raise ValueError("query参数为空，模型可能未正确抽取用户意图")
return v.strip()
def make_tool_call(func, raw_args: str):
import json, logging
try:
args = SearchArgs(**json.loads(raw_args))
except Exception as e:
logging.error(f"[args-invalid] raw={raw_args}, err={e}")
raise # 让失败显式暴露，而不是静默返回空
return func(**args.model_dump())
另外要重点检查工具的schema描述。如果工具描述写得含糊，模型在多轮对话后就容易乱传参数。实践经验是：参数描述里明确写出格式要求和示例，能显著降低空参数的概率。比如在描述中注明参数必须是具体的关键词，不要传入完整的用户原话，模型的抽取准确率会明显提升。
三、审查响应解析逻辑与数据边界情况
第三个常见原因是解析环节的缺陷。很多第三方API返回的是嵌套很深的JSON结构，如果解析路径写错了，比如取错层级或者字段名大小写不一致，结果就会是空。还有一种情况是API返回了合法但为空的数据集，比如查询结果本身就没有匹配项，这与解析错误需要区分开。
建议用防御性解析逐步打印中间结果：
def safe_parse(response: dict):
data = response.get("data")
if data is None:
print("第一层data缺失，原始响应:", response)
return []
items = data.get("items", [])
if not items:
print("items为空，可能是查询无匹配，code=", data.get("code"))
return []
return [i.get("name", "") for i in items]
除了解析问题，还要注意超时与限流。当外部API因为限流返回空body、或者请求超时被框架捕获后填了默认空值，表现同样是空结果。给每个工具调用设置独立的超时时间，并在超时时区分对待，是提高可观测性的关键。可以用一个对照表快速定位：
| 故障表现 | 常见根因 | 排查手段 |
|---|---|---|
| 返回None | 函数分支未覆盖、异常被吞 | 入口出口日志、异常标记 |
| 返回空列表 | 过滤条件过严、数据无匹配 | 直接用相同参数手工调API对照 |
| 返回空字符串 | 字段取错层级、编码问题 | 打印完整原始JSON |
| 偶发为空 | 超时、限流、网络抖动 | 重试机制加退避策略 |
最后推荐一个实用技巧：为每个工具建立回放机制，把每次调用的入参、原始响应、解析结果完整落盘。当出现空结果时，可以直接回放当时的输入做本地复现，这比在在线环境反复猜测高效得多。通过参数校验、显式异常、防御性解析和完整日志这四层防护的组合，绝大多数Agent工具调用空结果问题都能在短时间内定位到根因。