AI Agent / 系统课时
排查常见运行故障
排查常见运行故障
这节建立一套可复用的 Agent 运行故障定位顺序:先固定最小请求和请求 ID,再按网络、模型与提示词、工具、状态、数据逐层找出第一个失效边界,避免靠重启或反复改提示词碰运气。
学习目标
- 能把“无响应、报错、答非所问、工具失败、状态错乱”映射到正确排查层
- 能用最小请求、请求 ID 和结构化日志保存可比较证据
- 能在修复后用同一输入复测,确认问题真正消失
先按症状选择第一检查点
先检查服务和探针,再查看一次真实业务请求的 HTTP 状态、响应体中的业务状态和请求 ID。HTTP 状态要结合产生位置解读。例如 504 既可能由网关产生,也可能是应用把订单工具超时映射为 504。
| 现象 | 优先检查 | 第一证据 |
|---|---|---|
| 没收到 HTTP 响应 | DNS、连接、TLS、客户端超时 | curl 退出状态与入口日志 |
| 存活成功、就绪失败 | 订单库是否可读、运行权限 | /readyz、应用日志、配置和部署变更 |
| 401 或 404 | 认证与订单访问范围 | 401 的挑战头、404 的统一业务状态;通过受控审计区分无记录与越权 |
| 400、413 或 415 | 请求解析与大小限制 | 请求类型、字段契约及入口限制 |
| 已查询但状态不符 | 工具、数据范围和当前记录 | 实际租户/用户隔离、更新时间、可信数据源 |
| 后续增加模型才出现答复异常 | 模型与解释层 | 实际工具结果、模型完成状态、提示词版本 |

固定一个最小复现请求
在第 05 课服务运行时,从保有同一课堂令牌的 Bash 环境执行以下脚本。每次新请求从响应中读取服务器生成的请求 ID。只打印诊断所需的 HTTP 状态、时长和业务状态。
bash
set -eu
: "${DEMO_TOKEN:?请先配置第 05 课的课堂令牌}"
BASE_URL="${AGENT_BASE_URL:-http://127.0.0.1:8000}"
tmp="$(mktemp -d)"
trap 'rm -f "$tmp/headers" "$tmp/body"; rmdir "$tmp"' EXIT
curl -sS --connect-timeout 1 --max-time 3 \
-D "$tmp/headers" -o "$tmp/body" \
-w 'http=%{http_code} seconds=%{time_total}\n' \
"$BASE_URL/agent/run" \
-H "Authorization: Bearer $DEMO_TOKEN" -H 'Content-Type: application/json' \
-d '{"intent":"order_status","order_id":"ORD-20260904-001"}'
request_id="$(awk 'tolower($1)=="x-request-id:" {gsub(/\r/,"",$2); print $2; exit}' "$tmp/headers")"
printf 'request_id=%s\n' "${request_id:-missing}"
python - "$tmp/body" <<'PY'
import json
import sys
with open(sys.argv[1], encoding="utf-8") as body:
try:
data = json.load(body)
except ValueError:
print("business_status=unavailable")
else:
status = data.get("status", "unavailable") if isinstance(data, dict) else "unavailable"
print(f"business_status={status}")
PY正常输出形态
text
http=200 seconds=<TIME>
request_id=<ID>
business_status=ok此脚本保留 HTTP 非 2xx 响应用于排障。连接或传输故障时,curl 返回非零并退出。拿到 ID 后,在第 05 课本地 Uvicorn 终端或容器日志中查找同一 ID。容器示例可执行 docker logs agent-demo 2>&1 | grep -F -- '<ID>',其中 <ID> 换成实际 ID。若 ID 缺失,先确认响应是不是由网关、其他实例或框架错误页生成。
用同一输入复测
先请求一次正常订单,核对 200、业务状态、请求 ID 与 order_lookup 日志。再去掉认证头或换用测试库里不存在的编号,复核 401、404 及响应中没有订单详情。若问题涉及数据更新,用临时测试库更新状态后复测,确认输出来自本次读取。若涉及权限,增加另一租户相同订单号的用例。
记录修复前后的版本、状态、耗时及对应日志。用户输入、令牌和个人字段不进入诊断记录。未来引入外部模型或副作用工具后,分别加入模型完成状态、外部操作键和结果核对,避免将一个未证实完成的动作盲目重发。
按自己的节奏,确认真正理解。