Metadata-Version: 2.4
Name: agentguard47
Version: 1.3.2
Summary: Zero-dependency runtime control for production Python agents - stop loops, retry storms, and budget burn
Author-email: BMD PAT LLC <pat@bmdpat.com>
License-Expression: MIT
Project-URL: Homepage, https://agentguard47.com
Project-URL: Documentation, https://github.com/bmdhodl/agent47#readme
Project-URL: Repository, https://github.com/bmdhodl/agent47
Project-URL: Issues, https://github.com/bmdhodl/agent47/issues
Project-URL: Changelog, https://github.com/bmdhodl/agent47/releases
Keywords: agents,coding-agents,ai-agents,multi-agent,llm,guardrails,runtime-guardrails,loop-detection,budget-guard,retry-guard,runtime-enforcement,runtime-control,production-agents,coding-agent-safety,local-first,retry-storms,budget-control,langchain,openai,anthropic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: langchain
Requires-Dist: langchain-core>=1.6.3; extra == "langchain"
Provides-Extra: langgraph
Requires-Dist: langgraph>=1.2.11; extra == "langgraph"
Requires-Dist: langgraph-checkpoint>=4.2.0; extra == "langgraph"
Requires-Dist: langgraph-sdk>=0.4.4; extra == "langgraph"
Provides-Extra: crewai
Requires-Dist: crewai>=1.15.21; extra == "crewai"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.44.0; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.44.0; extra == "otel"
Dynamic: license-file

<!-- Generated by scripts/generate_pypi_readme.py. Edit README.md and CHANGELOG.md instead. -->

# AgentGuard

Stop runaway agents with runtime checks in Python.

[![PyPI version](https://img.shields.io/pypi/v/agentguard47)](https://pypi.org/project/agentguard47/)
[![Python versions](https://img.shields.io/pypi/pyversions/agentguard47)](https://pypi.org/project/agentguard47/)
[![CI](https://github.com/bmdhodl/agent47/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bmdhodl/agent47/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/github/license/bmdhodl/agent47)](https://github.com/bmdhodl/agent47/blob/v1.3.2/LICENSE)

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:

```bash
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.

```python
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:

```bash
python -m pip install openai
```

```python
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](https://github.com/bmdhodl/agent47/blob/main/docs/guides/getting-started.md)
for setup, traces, and framework starters.

## How enforcement works

```mermaid
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.

| Guard | Checks | Raises |
| --- | --- | --- |
| `BudgetGuard` | Recorded calls, tokens, or estimated cost | `BudgetExceeded` |
| `LoopGuard` | Repeated tool calls | `LoopDetected` |
| `FuzzyLoopGuard` | Tool frequency and alternating patterns | `LoopDetected` |
| `RetryGuard` | Retries per tool | `RetryLimitExceeded` |
| `TimeoutGuard` | Elapsed time when checked | `TimeoutExceeded` |
| `RateLimitGuard` | Calls within a sliding minute | `BudgetExceeded` |
| `X402SpendGuard` | Payment amounts before the payment callback | `BudgetExceeded` |

For task budgets, use `BudgetGuard.goal(...)`. For signatures and defaults,
read the [guard source](https://github.com/bmdhodl/agent47/blob/v1.3.2/sdk/agentguard/guards.py) and
[public exports](https://github.com/bmdhodl/agent47/blob/v1.3.2/sdk/agentguard/__init__.py).

## 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](https://github.com/bmdhodl/agent47/blob/v1.3.2/SECURITY.md), the
[dated dependency audit](https://github.com/bmdhodl/agent47/blob/v1.3.2/proof/audit-20260912/README.md), and
[release notes](https://github.com/bmdhodl/agent47/blob/v1.3.2/CHANGELOG.md). 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](https://github.com/bmdhodl/agent47/blob/main/docs/guides/dashboard-contract.md) 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](https://bmdpat.com/tools/agentguard?utm_source=agentguard47&utm_medium=readme&utm_campaign=touchpoints)
describes the optional hosted service.

## Documentation

| You want to | Start here |
| --- | --- |
| Install and trace a first run | [Getting started](https://github.com/bmdhodl/agent47/blob/main/docs/guides/getting-started.md) |
| Find guides and source references | [Documentation index](https://github.com/bmdhodl/agent47/blob/main/docs/README.md) |
| Try a runnable example | [Examples](https://github.com/bmdhodl/agent47/tree/v1.3.2/examples) |
| Connect LangChain, LangGraph, or CrewAI | [Integration guides](https://github.com/bmdhodl/agent47/tree/v1.3.2/docs/integrations) |
| Inspect hosted data through MCP | [Read-only TypeScript MCP server](https://github.com/bmdhodl/agent47/tree/v1.3.2/mcp-server) |
| Use local budget tools through MCP | [Python budget MCP server](https://github.com/bmdhodl/agent47/tree/v1.3.2/agentguard-mcp) |
| Navigate with an AI assistant | [AI documentation index](https://github.com/bmdhodl/agent47/blob/main/llms.txt) |
| Contribute a fix | [Contributing](https://github.com/bmdhodl/agent47/blob/v1.3.2/CONTRIBUTING.md) |
| Check what changed | [Changelog](https://github.com/bmdhodl/agent47/blob/v1.3.2/CHANGELOG.md) |

## Help and maintenance

Maintained by [Patrick Hughes](https://github.com/bmdhodl).
[Report a bug](https://github.com/bmdhodl/agent47/issues) with the package
version, a minimal reproduction, and the expected result. Report vulnerabilities
through [SECURITY.md](https://github.com/bmdhodl/agent47/blob/v1.3.2/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](https://github.com/bmdhodl/agent47/blob/v1.3.2/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](https://github.com/bmdhodl/agent47/blob/v1.3.2/CHANGELOG.md)
