PydanticAI 的 Agent 安全与限制实践

PydanticAI 的 Agent 安全与限制实践

学习目标

补充理解：

• UsageLimits 用量控制的强制执行机制
• SSRF 防护（_ssrf.py）
• ModelRetry 重试预算的设计
• Tool Approval 机制

前置知识

• 安全沙箱 — 通用安全沙箱概念

---

1. UsageLimits 用量控制

PydanticAI 在框架层强制执行用量限制：

UsageLimits:
    request_limit: int | None      # 最大请求次数
    token_limit: int | None        # 最大 token 数
    time_limit: float | None       # 最大时间（秒）
    retry_limit: int | None        # 最大重试次数

强制机制：

• 每次 ModelRequestNode 执行后检查用量
• UsageLimitExceeded 在达到限制时立即终止——不会优雅完成当前步骤
• 用量追踪在 GraphAgentState.usage 中累积

与通用速率限制的差异：

• 通用速率限制通常是请求级别的（如每分钟最多 N 次请求）
• PydanticAI 的 UsageLimits 是Agent 运行级别的——限制单次运行的总用量，防止无限循环和费用失控

2. SSRF 防护

_ssrf.py 实现服务端请求伪造（SSRF）防护：

• 验证 URL 不是内网地址
• 阻止对 localhost、169.254.169.254（AWS metadata）等的请求
• 应用于 WebFetch 等需要访问外部 URL 的工具

3. ModelRetry 重试预算

工具调用失败时的重试机制：

每个工具独立计数: ctx.retries[name]
达到上限: retries[name] == max_retries → UnexpectedModelBehavior

设计决策：

• 重试预算按工具独立计数——一个工具的失败不影响其他工具的预算
• max_retries 可在 Agent 级别和工具级别分别设置
• 验证失败和调用失败共用同一预算

4. Tool Approval 机制

工具审批在 PydanticAI 中通过 deferred tool 实现：

1. 工具执行后抛出 ApprovalRequired 异常
2. handle_call() 捕获异常，创建 DeferredToolRequests
3. HandleDeferredToolCalls Capability 处理审批
4. ToolApproved → 重新验证（可选 override_args）并重新执行
5. ToolDenied → ToolReturnPart(outcome='denied') 反馈给模型

重要：审批是在工具执行后触发的——工具已经运行，但结果被 hold 住。这不是预防性的拦截。