AgentGuard (this repository is named agent47, the PyPI package is named agentguard47, and the Python import is named agentguard) is a Python runtime inspection tool for AI agents, intended to stop runaway agents with runtime checks. The base SDK has no runtime dependencies and requires no account. This repository is agent47, the PyPI package is agentguard47, and the Python import is agentguard. AgentGuard 2.0.0 requires Python 3.11 or higher; on Python 3.9 or 3.10, you must pin agentguard47==1.4.0, and please refer to the Python migration guide before upgrading.
Main capabilities: AgentGuard checks budget, repeated tool calls, retries, and elapsed time. Guards raise exceptions so that the application stops the next operation. The base SDK has no runtime dependencies and requires no account.
Usage: install in a virtual environment, then run an offline check: use doctor to check the installation and local trace writing; demo exercises budget, loop, and retry stops without a provider key or network access, and inspect the output according to the trace path printed by the command; agentguard demo --feedback prints a local redacted report and does not send anything. For a fresh PowerShell installation and runnable raw getting-started steps, follow the operating instructions for the published version.
2.0.0 adds shareable stop receipts: agentguard receipt agentguard_demo_traces.jsonl prints a receipt for each stop and renders the trace's SHA-256 as a barcode; add --format markdown to paste it into a PR or issue. The hash identifies the trace file, but it is not a signature.
2.0.0 adds guarding Claude Code sessions: this installs a Claude Code hook that rejects the third consecutive identical tool call, as well as calls that have already failed twice. Rejection records are written to .agentguard/claude-code/trace.jsonl. It checks tool calls, not tokens or subscription quotas. See the Claude Code hook guide.
2.0.0 adds the ability to [text cuts off while still translating: without editing scripts]Guardable script: this patches the OpenAI and Anthropic clients, then runs agent.py in the same interpreter. Settings come from command-line flags, then environment variables, then .agentguard.json. A guard stop ends with exit code 1. At the end of each run, the trace path is shown on stderr so that agentguard receipt can use it. agentguard run python -m mypkg also works. The boundary is the same as patching the clients yourself; see Execution boundary.
agentguard run prices each patched call at the paid rate, including local models run through an OpenAI-compatible URL such as Ollama. Thus a dollar budget can stop a model that actually costs nothing. For local models, patch the client in the script with free_local_clients=[client], set BudgetGuard's token or call limit, and then run the script with python; see Free local clients.
Stop before the third call: save that code as budget_demo.py and run python budget_demo.py; it will not make network requests. Expected output: Stopped before call 3.
Connect a provider: install the provider's client separately. For OpenAI: the standard OpenAI client (including resource objects obtained before patching) is also covered. Activate the patch before sending a request or saving bound methods and raw/streaming response helper functions. These saved references may retain the original callables; recreate them after activation. patch_openai_async() covers asynchronous clients, and agentguard.init() enables both. See Execution boundary. The patch checks recorded usage before dispatch and records response usage afterward, including streaming calls after the final usage arrives. Responses may exceed the remaining cost or token quota. Concurrent requests do not reserve capacity. Chat Completions streaming requests include include_usage unless the caller has already set it. The OpenAI Agents SDK runs on responses.create, so calling agentguard.init() before Runner allows eachModel calls are placed under a budget (example). Does not cover hosted tools or responses with background=True. See the getting started guide for setup, tracing, and framework onboarding.
Execution mode: the text equivalent is: check before the operation, run if allowed, then record usage. Guard exceptions return control to the application's error handler. For task budgets, use BudgetGuard.goal(...). For signatures and defaults, read the guard source and public exports.
Limitations and safety: The guard covers the operations you instrument. Installing the package does not intercept every action in Cursor, Claude Code, or other agents. The guard is not a sandbox or permission system. Allowed operations can still be destructive. Timeout checks do not interrupt an already-blocked function, nor do they cancel an agent running on a provider's servers. Cost estimates are not invoices. When estimates are insufficient, provide reported costs or use strict cost parsing. Recorded budget pre-checks reject the next instrumented call when stored usage has already reached the cap. It does not reserve concurrent in-flight requests, predict the next response, or limit provider subscriptions. See execution boundaries. The base SDK uses the standard library. Optional framework add-ons install third-party dependencies and require your own security review. The optional [crewai] add-on pulls in ChromaDB. A 2026-09-12 audit found four unresolved advisories, including PYSEC-2026-311 / CVE-2026-45829. Review that exposure before installing the add-on. The base SDK installation does not include ChromaDB. Traces may contain application data. Review before sharing or configuring remote sinks. See the security report, dated dependency audit, and release notes. Audit results describe the date they were recorded, not a permanent certificate of health.
Local tracing and optional hosted integration: The SDK is a free local proof path. Start locally. Only add hosted integration when you need retained history, alerts, team visibility, spend trends, hosted decision history, or dashboard-managed remote kill signals. The local guard remains authoritative. HttpSink mirrors traces and decision events; it does not itself enforce remote kill signals. See the dashboard contract before configuring. Local usage has no hosted event quota, retention period, or API key allocation. Network egress requires an integration you configure, such as HttpSink or an OpenTelemetry exporter. The local SDK does not proactively send information externally. The AgentGuard website describes the optional hosted service.
Help and maintenance: Maintained by Patrick Hughes. When reporting a bug, please provide the package version, a minimal reproduction, and the expected result. Report vulnerabilities via SECURITY.md. Source metadata defines the branch version. PyPI badges link to published versions. Documentation examples and local links are tested in CI. The PyPI README is generated from this README and the changelog.
Python runtime checks for AI agents: budgets, loops, retries, and local tracing. Zero runtime dependencies. MIT.
