Agent工具调用与异常治理 - 第3节

3. 工具认证失败

认证失败是 Agent 调用外部工具时最高频的错误之一，其表象多样但根因集中。本章围绕 Token/密钥、OAuth 流程、凭证刷新机制 三大维度构建排查体系。首先建立故障识别标准：当 Agent 返回 401 Unauthorized、403 Forbidden 或自定义认证错误码时，即可进入本章排查流程。

进入正式排查前，请确认 Agent 日志级别已设为 DEBUG 或 TRACE，并开启原始请求/响应记录功能。以下为本节排查全景图：

3.2 数据采集：捕获认证凭证与交互日志

在定位根因之前，必须采集到完整的认证上下文。采集目标包括：

1. Agent 请求日志：完整 HTTP 请求头（不含敏感字段的哈希值）、响应头、时间戳。重点关注 Authorization / Bearer 头部前 20 个字符。
2. 凭证存储：环境变量、密钥管理服务（KMS）拉取的 Token/密钥内容摘要（不输出原文，仅输出过期时间、权限 Scope、签发者）。
3. OAuth 状态：回调 URL、授权码是否存在、Refresh Token 是否有效、Scope 列表。
4. 系统时钟：Agent 所在容器/主机的 NTP 同步状态与时间偏移量。

# 查看 Agent 日志中认证相关条目（示例为 systemd journal）
journalctl -u agent-service --since "5 min ago" | grep -E "(401|403|auth|token|expired)"

# 测试 Token 是否有效（直接调用工具 API）
curl -v -H "Authorization: Bearer <TOKEN>" https://api.example.com/v1/verify

# 检查系统时间偏移
timedatectl show --property=NTPSynchronized --value
chronyc tracking | grep "Last offset"

数据采集清单

3.3 原因定位：Token/密钥的逐层诊断

采集到数据后，先按故障树对 Token 与密钥展开系统化检查。

3.3.1 检查 Token 过期 (exp)

使用 JWT 解码工具查看 exp 时间戳，并与当前系统时间对比。若 Token 已过期，Agent 应使用 Refresh Token 自动续期；若未实现自动刷新，则直接判定为根因。

# 解码 JWT（示例为 jwt-cli 工具）
jwt decode <TOKEN> | grep exp

# 输出示例
exp: 1719878400 (2024-07-02 00:00:00 UTC)
# 当前时间
date -u
Tue Jul  2 00:05:00 UTC 2024  → Token 已过期 5 分钟

3.3.2 检查签名算法与密钥对

若 Token 未过期，可能是因为 Agent 使用了错误的密钥对（或密钥轮换后未同步）。检查点：

• 签名算法与工具平台声明一致（如 HS256 使用对称密钥，RS256 使用非对称密钥对）。
• Agent 配置的公钥/私钥是否与工具平台最新注册的密钥匹配。
• 密钥类型不要混淆（如将 PEM 格式误传为 JWK 格式）。

# 验证 JWT 签名（使用 openssl）
echo "<jwt_header>.<jwt_payload>.<jwt_signature>" | \
  openssl dgst -sha256 -verify <public_key.pem> -signature <(echo "<jwt_signature>" | base64 -d)

3.3.3 检查环境变量与配置文件

检查 Token/密钥的加载路径：

• 环境变量名是否拼写错误（常见为 API_KEY 与 API_KEy 的差异）。
• 配置文件中的密钥是否为明文，且未被错误转义（如包含 $ 符号被 Shell 解释）。
• Agent 运行时的 umask 或文件权限是否过低导致密钥文件无法读取。

# 检查环境变量是否存在且非空
echo "API_KEY length: ${#API_KEY}"
if [ -z "$API_KEY" ]; then echo "ERROR: API_KEY not set"; fi

# 检查配置文件权限
ls -la /etc/agent/config.yaml | awk '{print $1, $4, $9}'
# 应类似 -r-------- root root config.yaml

3.4 原因定位：OAuth 流程诊断

当 Token 自身有效但仍认证失败时，需排查 OAuth 授权流程是否完整。

OAuth 完整流程参考

// 伪代码：Agent 使用 Refresh Token 获取 Access Token
POST /oauth/token HTTP/1.1
Host: auth.tool.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<REFRESH_TOKEN>
&client_id=<CLIENT_ID>
&client_secret=<CLIENT_SECRET>
&scope=read+write

典型的 OAuth 拒绝 响应应包含 error 字段，如 invalid_grant、unauthorized_client，这些都是可追溯的根因信号。

3.5 修复动作：凭证刷新与缓存策略

定位到根因后，实施标准化修复。本章重点介绍凭证自动刷新机制：

1. 实现 Token 自动续期：在 Agent 初始化阶段获取 Access Token，并开启一个后台定时任务，在 Token 过期前（通常保留 60 秒缓冲）使用 Refresh Token 换取新 Token。
2. 配置本地缓存 + 失效重试：将当前 Token 保存在内存或本地缓存中，当 API 返回 401 时，立即触发一次刷新，重试失败请求（最多 2 次）。
3. 初始化阶段预刷新：Agent 启动后立即检查现有 Token 的有效期，若剩余时间小于 5 分钟，则触发提前刷新。

# 1. 验证 Refresh Token 有效性
if [ $(jwt decode $REFRESH_TOKEN | jq -r '.exp') -lt $(date +%s) ]; then
  echo "Refresh Token expired, re-authorization required"
  exit 1
fi

# 2. 换取新 Access Token
NEW_TOKEN=$(curl -s -X POST "https://auth.tool.com/oauth/token" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$REFRESH_TOKEN" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" | jq -r '.access_token')

# 3. 更新内存/缓存中的 Token
echo $NEW_TOKEN > /tmp/agent_latest_token
# 实际生产环境应使用 密钥管理服务 (KMS) 或 Secure Store

# 4. 重试之前失败的工具调用
retry_original_request

3.6 复测验证与预防机制

完成修复后，执行以下复测步骤：

• 功能复测：Agent 再次调用之前失败的工具 API，验证返回 200 OK。
• 边界复测：手动将系统时钟拨快 10 分钟，验证 Agent 是否自动触发 Token 刷新；将 Refresh Token 置为无效，验证 Agent 能否正确报错并引导重新授权。
• 监控接入：配置认证失败率告警（例如 5 分钟内失败 3 次即触发 Warning）。
• 自愈能力：Agent 框架应内置认证失败自动重试（附带去重机制），避免对工具 API 造成重复调用。