AgentGuard（本仓库名为 agent47，PyPI 包名为 agentguard47，Python 导入名为 agentguard）是一个用于 AI 智能体的 Python 运行时检查工具，目的是用运行时检查阻止失控的智能体。基础 SDK 没有运行时依赖，也不需要账号。该仓库为 agent47，PyPI 包为 agentguard47，Python 导入为 agentguard。AgentGuard 2.0.0 要求 Python 3.11 或更高版本；在 Python 3.9 或 3.10 上需固定 agentguard47==1.4.0，升级前请参阅 Python 迁移指南。
主要能力：AgentGuard 会检查预算、重复的工具调用、重试和经过时间。守卫会抛出异常，以便应用停止下一步操作。基础 SDK 没有运行时依赖，也不需要账号。
使用方式：在虚拟环境中安装，然后运行离线检查：使用 doctor 检查安装和本地追踪写入；demo 在没有提供方密钥或网络访问的情况下演练预算、循环和重试停止，并按照命令打印的追踪路径检查输出；agentguard demo --feedback 会打印本地脱敏报告，不会发送任何内容。对于全新的 PowerShell 安装和可运行的原始入门步骤，请遵循已发布版本的操作说明。
2.0.0 新增了分享停止回执：agentguard receipt agentguard_demo_traces.jsonl 会打印每次停止的回执，并将追踪的 SHA-256 绘制成条形码；添加 --format markdown 可粘贴到 PR 或 issue 中，该哈希标识追踪文件，但不是签名。
2.0.0 新增了守卫 Claude Code 会话：这会安装一个 Claude Code 钩子，拒绝连续第三次相同的工具调用，以及已经失败两次的调用。拒绝记录写入 .agentguard/claude-code/trace.jsonl。它检查工具调用，而不是令牌或订阅配额。参见 Claude Code 钩子指南。
2.0.0 新增了无需编辑脚本即可守卫脚本：这会给 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，它不会发起网络请求。预期输出：Stopped before call 3。
连接提供方：单独安装提供方的客户端。对于 OpenAI：标准 OpenAI 客户端（包括在打补丁之前获得的资源对象）也会被覆盖。在发送请求或保存绑定方法及原始/流式响应辅助函数之前激活补丁。这些已保存的引用可能会保留原始可调用对象；在激活后重新创建它们。patch_openai_async() 覆盖异步客户端，agentguard.init() 会同时启用两者。参见执行边界。该补丁在分发前检查记录的用量，并在之后记录响应用量，包括在最终用量到达后的流式调用。响应可能会超出剩余成本或令牌配额。并发请求不会预留容量。Chat Completions 流式请求包含 include_usage，除非调用方已经设置。OpenAI Agents SDK 运行在 responses.create 上，因此在 Runner 之前调用 agentguard.init() 可将每个模型调用置于预算之下（示例）。不覆盖托管工具和 background=True 的响应。参见入门指南了解设置、追踪和框架入门。
执行方式：文本等价为：操作前检查，允许则运行，然后记录用量。守卫异常将控制权返回给应用的错误处理器。对于任务预算，使用 BudgetGuard.goal(...)。有关签名和默认值，请阅读守卫源码和公共导出。
限制与安全：守卫覆盖你插桩的操作。安装该包不会拦截 Cursor、Claude Code 或其他智能体中的每个动作。守卫不是沙箱或权限系统。允许的操作仍然可能具有破坏性。超时检查不会中断已阻塞的函数，也不会取消在提供方服务器上运行的智能体。成本估算不是发票。当估算不足时，提供报告的成本或使用严格成本解析。记录预算预检在存储用量已达到上限时拒绝下一个插桩调用。它不会预留并发在途请求、预测下一个响应，也不会限制提供方订阅。参见执行边界。基础 SDK 使用标准库。可选的框架附加项会安装第三方依赖，需要自行进行安全审查。可选的 [crewai] 附加项会拉取 ChromaDB。2026-09-12 的审计发现四个未解决的公告，包括 PYSEC-2026-311 / CVE-2026-45829。在安装该附加项之前审查该暴露。基础 SDK 安装不包含 ChromaDB。追踪内容可能包含应用数据。在分享或配置远程接收器之前进行检查。参见安全报告、带日期的依赖审计和发布说明。审计结果描述其记录日期，并非永久健康证明。
本地追踪与可选托管接入：SDK 是免费的本地证明路径。从本地开始。仅在需要保留历史、警报、团队可见性、支出趋势、托管决策历史或仪表板管理的远程终止信号时，才添加托管接入。本地守卫保持权威。HttpSink 镜像追踪和决策事件；它本身不执行远程终止信号。在配置之前参见仪表板契约。本地使用没有托管事件配额、保留期或 API 密钥分配。网络出口需要你配置的集成，例如 HttpSink 或 OpenTelemetry 导出器。本地 SDK 不会主动向外部发送信息。AgentGuard 网站描述了可选的托管服务。
帮助与维护：由 Patrick Hughes 维护。报告 bug 时请提供包版本、最小复现和预期结果。通过 SECURITY.md 报告漏洞。源代码元数据定义分支版本。PyPI 徽章链接已发布版本。文档示例和本地链接在 CI 中测试。PyPI README 由本 README 和变更日志生成。
Python 运行时检查用于 AI 智能体：预算、循环、重试和本地追踪。零运行时依赖。MIT。
