agentguard47

AgentGuard

通过 Python 中的运行时检查，阻止失控的 Agent。

AgentGuard 会在经过插桩的 Python 代码中检查预算、重复工具调用、重试和耗时。守卫会抛出异常，以便应用停止下一步操作。基础 SDK 没有运行时依赖，也无需账户。

**名称：**此仓库名为 agent47，PyPI 包名为 agentguard47，Python 导入名为 agentguard。AgentGuard 2.0.0 需要 Python 3.11 或更高版本。在 Python 3.9 或 3.10 上，请固定使用 agentguard47==1.4.0。升级前请参阅 Python 迁移指南。

开始使用

在虚拟环境中安装，然后运行离线检查：

python -m pip install agentguard47
agentguard doctor
agentguard demo

doctor 会检查安装情况和本地轨迹写入。demo 会在无需提供商密钥或网络访问的情况下，演示预算、循环和重试拦截。按照命令打印的轨迹路径查看输出。 agentguard demo --feedback 会打印本地脱敏报告；不会发送任何内容。

如需在全新的 PowerShell 环境中安装并运行原始入门示例，请参阅 已发布版本上手指南。

分享拦截凭据（2.0.0 新增）

agentguard receipt agentguard_demo_traces.jsonl 会打印每次拦截的凭据，并以条形码形式显示轨迹的 SHA-256。添加 --format markdown 可将其粘贴到 PR 或 issue 中。此哈希用于标识轨迹文件，不是签名。此拦截凭据会记录一次被覆盖的守卫拒绝。Anthropic 官方的 /receipts 插件 会汇总过去的 Claude Code 工作（默认保留 30 天）。两种输出都无法证明已阻止支出，也不提供签名证明。agentguard receipt 命令保持不变。

为 Claude Code 会话添加守卫（2.0.0 新增）

agentguard hook claude-code --install --write

这会安装一个 Claude Code 钩子，拒绝连续第三次发起的相同工具调用，以及已经失败两次的调用。“相同”判断会忽略 JSON 键的顺序，并保留值中的大小写和空白字符。可选的 no_progress_max 规则会在工具反复返回空结果或相同错误时拒绝该工具调用，即使输入发生变化；默认关闭。拒绝记录不会包含原始输入，并会写入 .agentguard/claude-code/trace.jsonl。它 检查的是工具调用，而不是令牌或订阅配额。请参阅 Claude Code 钩子指南。

无需修改脚本即可为其添加防护（2.0.0 新增）

agentguard run --budget-usd 5 agent.py

此命令会修补 OpenAI 和 Anthropic 客户端，然后在同一解释器中运行 agent.py。设置的读取顺序为：命令行标志、环境变量，然后是 .agentguard.json。触发防护停止时，退出码为 1。每次运行结束时，都会将跟踪文件路径输出到 stderr，可直接用于 agentguard receipt。agentguard run python -m mypkg 也可以正常运行。其限制与自行修补客户端相同；请参阅强制执行边界。

子进程会启动独立的解释器，不会被父进程修补。脱离父进程且未经检测的子进程，可能在受防护脚本退出后继续运行。离线复现通过两个模拟调用且不访问网络，演示了这一边界。

agentguard run 会按付费费率为每次修补后的调用计价，包括通过 OpenAI 兼容 URL 访问的本地模型，例如 Ollama。这样一来，美元预算也会停止免费的模型。对于本地模型，请在脚本中使用 free_local_clients=[client] 修补客户端，并使用 BudgetGuard 的令牌数或调用次数上限，然后通过 python 运行脚本；请参阅免费本地客户端。

在第三次调用前停止

将以下内容保存为 budget_demo.py，然后运行 python budget_demo.py。它不会发起网络请求。

from agentguard import BudgetExceeded, BudgetGuard

budget = BudgetGuard(max_calls=2)
completed = 0

for _ in range(3):
    try:
        budget.check()  # Check before the operation.
        # Put your provider or tool call here.
        completed += 1
        budget.consume(calls=1)  # Record the completed operation.
    except BudgetExceeded:
        print(f"Stopped before call {completed + 1}")

assert completed == 2

预期输出：Stopped before call 3。

停止措辞不同的循环

陷入停滞的 Agent 往往会在每次重试时改写措辞，因此没有任何调用会完全重复。 max_no_progress 会改为统计结果：同一个工具连续 N 次返回空结果或相同错误时，无论参数是什么，都会停止运行。normalize=True 会规范化容器，同时保留参数值中的大小写和空白。默认情况下，这两个选项均处于关闭状态。

from agentguard import LoopDetected, LoopGuard

loop = LoopGuard(normalize=True, max_no_progress=3)

for pattern in ["retry_count", "retryCount", "retries"]:
    loop.check("grep", {"pattern": pattern})
    matches = []  # Put your search here. This one finds nothing.
    try:
        loop.record_result("grep", matches, tool_args={"pattern": pattern})
    except LoopDetected as stop:
        print(stop)

预期输出：No progress: grep came back empty 3 times in a row (limit: 3). Change the approach instead of rewording the call. 使用 trace_tool 包装的函数会自动将结果提供给防护机制。中间出现任何其他结果都会重新开始计数，因此分页和编辑后测试的循环不会触发停止。

连接提供商

请单独安装提供商的客户端。以 OpenAI 为例：

python -m pip install openai

from agentguard import BudgetGuard, JsonlFileSink, Tracer, patch_openai

budget = BudgetGuard(max_cost_usd=5.00)
tracer = Tracer(
    service="my-agent",
    sink=JsonlFileSink(".agentguard/traces.jsonl"),
)
patch_openai(tracer, budget_guard=budget)
# Make your OpenAI chat.completions.create or responses.create calls after this setup.

较早创建的标准 OpenAI 客户端也会受到防护，包括在修补前获取的资源对象。请在发送请求或保存绑定方法和原始／流式响应辅助函数之前启用修补。已保存的引用可能仍指向原始可调用对象；请在启用后重新创建这些引用。patch_openai_async() 会覆盖异步客户端，agentguard.init() 则会同时启用两者。请参阅强制执行边界。

修补程序会在分发前检查已记录的用量，并在之后记录响应用量，包括等待流式调用收到最终用量后再记录。响应的用量可能超过剩余费用或令牌额度。并发请求不会预留额度。Chat Completions 流式调用会请求 include_usage，除非调用方已设置该参数。

OpenAI Agents SDK 基于 responses.create 运行，因此在 Runner 之前调用 agentguard.init()，即可将每次模型调用纳入预算控制（示例）。托管工具和 background=True 响应不在覆盖范围内。请参阅入门指南，了解设置、跟踪记录和框架入门示例。

执行方式

flowchart TD
    accTitle: AgentGuard operation checks
    accDescr: Check a limit before an operation, then record usage.
    A[Instrumented operation] --> B{Guard check}
    B -->|Limit reached| C[Raise exception]
    B -->|Allowed| D[Run operation]
    D --> E[Record usage and trace]
    E --> A

文字说明：操作前检查；如果获准，则执行操作，然后记录用量。守卫异常会将控制权交给应用程序的错误处理程序。

守卫	检查内容	引发的异常
BudgetGuard	已记录的调用、令牌或预估费用	BudgetExceeded
LoopGuard	重复的工具调用；启用 normalize=True 和 max_no_progress=N，以检测改写后的调用	LoopDetected
FuzzyLoopGuard	工具调用频率和交替模式	LoopDetected
RetryGuard	每个工具的重试次数	RetryLimitExceeded
TimeoutGuard	检查时已流逝的时间	TimeoutExceeded
RateLimitGuard	滑动一分钟内的调用次数	BudgetExceeded
X402SpendGuard	支付回调前的支付金额	BudgetExceeded

如需设置任务预算，请使用 BudgetGuard.goal(...)。有关签名和默认值，请参阅守卫源代码和公开导出项。

预算也可以跨运行持久化：配置 JsonFileStateStore、共享 key，并设置 period="day"，即可使用每日计数器。设置 warn_at_pct=0.8 和 on_warning 回调，即可在用量达到 80% 时发出警告。工作进程必须显式共享存储和键；子 Agent 不会自动继承预算。SDK 尚未实现每月限额。请参阅能力矩阵。

限制与安全

• 守卫只覆盖经过你插桩的操作。安装此软件包不会拦截 Cursor、Claude Code 或其他 Agent 中的所有操作。
• 守卫不是沙箱或权限系统。获准的操作仍可能造成破坏。
• 超时检查不会中断已经阻塞的函数，也不会取消在服务提供商服务器上运行的 Agent。
• 费用估算不是账单。如果估算不足以满足需求，请提供报告的费用，或使用严格费用解析。
• 记录预算的预检会在已存储用量达到上限时，拒绝下一次经过插桩的调用。它不会为并发的进行中请求预留额度、预测下一个响应，也不会限制服务提供商订阅。请参阅执行边界。
• 基础 SDK 使用标准库。可选框架附加组件会安装第三方依赖项，需单独进行安全审查。
• 可选的 [crewai] 附加组件会引入 ChromaDB。2026-09-12 审计发现了 4 项尚未解决的安全公告，其中包括 PYSEC-2026-311 / CVE-2026-45829。安装该附加组件前，请评估相关风险。基础 SDK 的安装不包含 ChromaDB。
• 跟踪内容可能包含应用程序数据。分享跟踪内容或配置远程接收端之前，请先进行检查。

请参阅安全问题报告、注明日期的依赖项审计和发行说明。审计结果仅反映记录的日期，并不代表永久安全无虞。

本地跟踪与可选的托管摄取

SDK 是免费的本地验证途径。请先从本地使用开始。只有在需要保留历史记录、告警、团队可见性、支出趋势、托管决策历史记录或由仪表板管理的远程终止信号时，才添加托管摄取。

本地守卫仍具有最终裁定权。HttpSink 会镜像跟踪和决策事件；它本身不会执行远程终止信号。配置前请参阅仪表板约定。

本地使用没有托管事件配额、保留期限或 API 密钥分配。网络出站流量需要你配置集成，例如 HttpSink 或 OpenTelemetry 导出器。

本地 SDK 中没有任何内容会向外发送数据。AgentGuard 网站介绍了可选的托管服务。

文档

你想要	从这里开始
查看哪些路径会实际阻止调用	执行边界
安装并跟踪首次运行	入门指南
查找指南和源码参考	文档索引
尝试可运行的示例	示例
连接 LangChain、LangGraph 或 CrewAI	集成指南
通过 MCP 检查托管数据	只读 TypeScript MCP 服务
通过 MCP 使用本地预算工具	Python 预算 MCP 服务
使用 AI 助手浏览	AI 文档索引
贡献修复	贡献指南
查看更改内容	更新日志

帮助与维护

由 Patrick Hughes 维护。 报告错误时，请提供软件包 版本、最小复现示例和预期结果。请通过 SECURITY.md 报告漏洞。

源代码元数据定义分支版本。PyPI 徽章链接到已发布的版本。文档示例和本地链接会在 CI 中测试。 PyPI README 根据此 README 和更新日志生成。

MIT 许可证。