AgentGuard

Stop runaway agents with runtime checks in Python.

AgentGuard checks budgets, repeated tool calls, retries, and elapsed time in instrumented Python code. Guards raise exceptions so your application can stop the next operation. The base SDK has no runtime dependencies and needs no account.

Names: this repository is agent47, the PyPI package is agentguard47, and the Python import is agentguard. Requires Python 3.9 or newer.

Getting started

Install in a virtual environment, then run the offline checks:

python -m pip install agentguard47
agentguard doctor
agentguard demo

doctor checks the installation and local trace writing. demo exercises budget, loop, and retry stops without provider keys or network access. Follow the trace path printed by the command to inspect its output.

Stop before a third call

Save this as budget_demo.py and run python budget_demo.py. It makes no network requests.

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

Expected output: Stopped before call 3.

Connect a provider

Install the provider's client separately. For 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 calls after this setup.

The patch checks recorded usage before dispatch and records response usage afterward, including streamed calls once the final usage arrives. A response can exceed the remaining cost or token allowance. Concurrent requests do not reserve capacity. OpenAI streams request include_usage unless the caller already set it. See the getting started guide for setup, traces, and framework starters.

How enforcement works

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

Text equivalent: check before an operation, run it if allowed, then record usage. A guard exception returns control to your application's error handler.

For task budgets, use BudgetGuard.goal(...). For signatures and defaults, read the guard source and public exports.

Limits and security

• Guards cover operations you instrument. Installing the package does not intercept every action in Cursor, Claude Code, or another agent.
• A guard is not a sandbox or permission system. A permitted operation can still be destructive.
• Timeout checks do not interrupt an already blocked function or cancel an agent running on a provider's server.
• Cost estimates are not invoices. Supply reported cost or use strict cost resolution when an estimate is insufficient.
• The base SDK uses the standard library. Optional framework extras install third-party dependencies and need their own security review.
• Trace content can contain application data. Review it before sharing or configuring a remote sink.

See security reporting, the dated dependency audit, and release notes. Audit results describe their recorded date, not a permanent clean bill of health.

Local traces and optional hosted ingest

The SDK is the free local proof path. Start local. Add hosted ingest only when you need retained history, alerts, team visibility, spend trends, hosted decision history, or dashboard-managed remote kill signals.

Local guards remain authoritative. HttpSink mirrors trace and decision events; it does not execute remote kill signals by itself. See the dashboard contract before configuring it.

Local use 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.

Nothing in the local SDK phones home. The AgentGuard website describes the optional hosted service.

Documentation

Help and maintenance

Maintained by Patrick Hughes. Report a bug with the package version, a minimal reproduction, and the expected result. Report vulnerabilities through SECURITY.md.

The source metadata defines the branch version. The PyPI badge links to the published version. Documentation examples and local links are tested in CI. The PyPI README is generated from this README and the changelog.

MIT license.

Latest Release Notes (1.3.2)

(2026-09-17)

Record final usage on streamed provider calls

• OpenAI and Anthropic patches now wrap stream=True responses and bill the final usage payload once, for both sync and async clients. Anthropic messages.stream() is included. Chunks without usage are ignored.
• OpenAI streaming requests set stream_options.include_usage=True when the caller did not set include_usage. An explicit False is left unchanged.
• Anthropic create(stream=True) events split input usage on message_start and output usage on message_delta; the wrapper now merges those fields before billing. Stream wrappers are iterators (next / anext). A failed stream closes the trace span with the exception so assert_no_errors() sees it.
• A stream that ends without usage still counts as one dispatched call with zero tokens and zero cost. Exhausted budgets still refuse the request before dispatch.
• This does not reserve concurrent capacity, predict a response's cost, or preflight goal-level caps. Mid-stream abort without a usage payload cannot recover tokens from partial text.
• Reproduce the before/after token counts without network calls with examples/streaming_usage_demo.py. The provider is mocked; the installed AgentGuard patch, stream wrapper, and budget consume path are real.

Full changelog: CHANGELOG.md