AI Agent / 系统课时

排查常见运行故障

排查常见运行故障

这节建立一套可复用的 Agent 运行故障定位顺序:先固定最小请求和请求 ID,再按网络、模型与提示词、工具、状态、数据逐层找出第一个失效边界,避免靠重启或反复改提示词碰运气。

学习目标

  • 能把“无响应、报错、答非所问、工具失败、状态错乱”映射到正确排查层
  • 能用最小请求、请求 ID 和结构化日志保存可比较证据
  • 能在修复后用同一输入复测,确认问题真正消失

先按症状选择第一检查点

先检查服务和探针,再查看一次真实业务请求的 HTTP 状态、响应体中的业务状态和请求 ID。HTTP 状态要结合产生位置解读。例如 504 既可能由网关产生,也可能是应用把订单工具超时映射为 504。

现象 优先检查 第一证据
没收到 HTTP 响应 DNS、连接、TLS、客户端超时 curl 退出状态与入口日志
存活成功、就绪失败 订单库是否可读、运行权限 /readyz、应用日志、配置和部署变更
401 或 404 认证与订单访问范围 401 的挑战头、404 的统一业务状态;通过受控审计区分无记录与越权
400、413 或 415 请求解析与大小限制 请求类型、字段契约及入口限制
已查询但状态不符 工具、数据范围和当前记录 实际租户/用户隔离、更新时间、可信数据源
后续增加模型才出现答复异常 模型与解释层 实际工具结果、模型完成状态、提示词版本

Agent 运行故障分层定位流程

固定一个最小复现请求

在第 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 及响应中没有订单详情。若问题涉及数据更新,用临时测试库更新状态后复测,确认输出来自本次读取。若涉及权限,增加另一租户相同订单号的用例。

记录修复前后的版本、状态、耗时及对应日志。用户输入、令牌和个人字段不进入诊断记录。未来引入外部模型或副作用工具后,分别加入模型完成状态、外部操作键和结果核对,避免将一个未证实完成的动作盲目重发。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查常见运行故障

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通