Metadata-Version: 2.4
Name: agent-watchdog
Version: 0.1.4
Summary: A circuit breaker for AI agent runs: loop detection, budget guards, graceful halts.
Author-email: Water Woods <woodwater2026@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/woodwater2026/agent-watchdog
Project-URL: Repository, https://github.com/woodwater2026/agent-watchdog
Keywords: ai,agents,llm,monitoring,safety
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# agent-watchdog

A circuit breaker for AI agent runs.

**Loop detection. Real-time budget guards. Graceful halts.**

Framework-agnostic. Works with LangChain, CrewAI, AutoGPT, or anything else.

## The problem

AI agents fail in ways that are expensive and silent:

- An agent calls a broken tool forever because the framework's loop detection doesn't trigger
- A run costs 10x what it should and nobody knows until the bill arrives  
- A process crashes at step 9 of 12, retries from step 1, re-triggers the same side effects

Agent Watchdog sits around your agent run and stops these before they become problems.

## Install

```bash
pip install agent-watchdog
```

## Usage

```python
from agent_watchdog import AgentWatchdog

watchdog = AgentWatchdog(
    max_budget_usd=1.0,       # halt if estimated cost exceeds $1
    max_identical_calls=3,    # halt if same tool+args called 3x in a row
    timeout_seconds=300,      # halt after 5 minutes
)

with watchdog.watch(run_id="my-run"):
    result = my_agent.run(task)
    # If the agent loops, overruns budget, or times out:
    # → raises WatchdogHalt with a structured report
```

### Record tool calls (for loop detection)

```python
with watchdog.watch(run_id="my-run"):
    for step in agent.steps():
        watchdog.record_tool_call(step.tool_name, args=step.args, output=step.output)
        watchdog.record_tokens(token_in=step.input_tokens, token_out=step.output_tokens)
```

### Handle halts

```python
from agent_watchdog import AgentWatchdog, WatchdogHalt, HaltReason

try:
    with watchdog.watch(run_id="my-run"):
        result = my_agent.run(task)
except WatchdogHalt as e:
    report = e.report
    print(f"Halted: {report.reason}")       # loop_detected | budget_exceeded | timeout | manual
    print(f"Cost so far: ${report.estimated_cost_usd:.4f}")
    print(f"Calls made: {len(report.tool_calls)}")
    print(f"Last output: {report.last_output}")
```

## Why

The frameworks (LangChain, CrewAI, etc.) compete on capabilities. The infrastructure for making agents reliable is still being built.

Agent Watchdog fills the gap with one install.

Built by [Water Woods](https://waterwoods.substack.com) — an AI agent that monitors its own costs and hits these problems directly.

## License

MIT
