agentmolt 0.2.0
Agent Control Panel — monitor, control, and kill-switch your AI agents
License: MIT
Requires Python: >=3.9
Keywords: ai, agents, monitoring, control-panel, kill-switch, observability, langchain, crewai, openai

# AgentMolt — Kill Switch & Budget Control for AI Agents

[![PyPI](https://img.shields.io/pypi/v/agentmolt)](https://pypi.org/project/agentmolt/)
[![Python 3.9+](https://img.shields.io/pypi/pyversions/agentmolt)](https://pypi.org/project/agentmolt/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

Monitor, budget-cap, and kill-switch your AI agents. Works standalone or with OpenAI/Anthropic/LangChain/CrewAI.

**→ [agentmolt.dev](https://agentmolt.dev)**

## Install

```bash
pip install agentmolt
```

## Quick Start — Try It Now (No API Key Needed)

```python
from agentmolt import ACP, AgentBudget

# Create a local control panel (no API key = local-only mode)
panel = ACP()

# Register an agent with a $5 budget
panel.register("my-agent", budget=AgentBudget(max_cost_usd=5.00))

# Simulate agent making API calls
for i in range(10):
    try:
        state = panel.log("my-agent", model="gpt-4o", tokens=1000, cost=0.80)
        print(f"Call {i+1}: ${state.total_cost_usd:.2f} spent, alive={panel.is_alive('my-agent')}")
    except Exception as e:
        print(f"Call {i+1}: KILLED — {e}")
        break
```

Output:
```
Call 1: $0.80 spent, alive=True
Call 2: $1.60 spent, alive=True
Call 3: $2.40 spent, alive=True
Call 4: $3.20 spent, alive=True
Call 5: $4.00 spent, alive=True
Call 6: $4.80 spent, alive=True
Call 7: KILLED — Agent 'my-agent' killed: cost $5.60 exceeded budget $5.00
```

The agent is automatically killed when it exceeds its budget. No more runaway costs.

## Kill Switch

```python
from agentmolt import ACP

panel = ACP()
panel.register("research-bot")

# Check if agent is alive
print(panel.is_alive("research-bot"))  # True

# Kill it manually
panel.kill("research-bot", reason="suspicious activity")
print(panel.is_alive("research-bot"))  # False

# Any future calls raise AgentKilledException
try:
    panel.log("research-bot", model="gpt-4o", tokens=100, cost=0.01)
except Exception as e:
    print(f"Blocked: {e}")

# Revive if needed
panel.revive("research-bot")
print(panel.is_alive("research-bot"))  # True
```

## Budget Enforcement

Set limits on cost, tokens, or number of calls:

```python
from agentmolt import ACP, AgentBudget

panel = ACP()

panel.register("writer-agent", budget=AgentBudget(
    max_cost_usd=10.00,   # Kill at $10 spent
    max_tokens=100_000,    # Kill at 100K tokens
    max_calls=50,          # Kill after 50 API calls
    alert_at_pct=0.8,      # Trigger alert at 80% of any limit
))
```

## Callbacks — Get Notified

```python
def on_kill(agent_id):
    print(f"🚨 ALERT: {agent_id} was killed!")

def on_alert(agent_id, pct):
    print(f"⚠️ WARNING: {agent_id} at {pct:.0%} of budget")

panel = ACP(
    on_kill=on_kill,
    on_alert=on_alert,
)

panel.register("spender", budget=AgentBudget(max_cost_usd=1.00, alert_at_pct=0.5))

panel.log("spender", model="gpt-4o", tokens=500, cost=0.30)
# → nothing

panel.log("spender", model="gpt-4o", tokens=500, cost=0.30)
# → ⚠️ WARNING: spender at 60% of budget

panel.log("spender", model="gpt-4o", tokens=500, cost=0.50)
# → 🚨 ALERT: spender was killed!
# → raises AgentKilledException
```

## Auto-Patch OpenAI (Zero Code Changes)

```python
from agentmolt import ACP
from openai import OpenAI

panel = ACP()
client = OpenAI()
panel.patch_openai(client)

# Use OpenAI as normal — all calls are automatically monitored
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

# Check what happened
for agent_id, state in panel.all_agents().items():
    print(f"{agent_id}: {state.total_calls} calls, ${state.total_cost_usd:.4f}")
```

## Auto-Patch Anthropic

```python
from agentmolt import ACP
import anthropic

panel = ACP()
client = anthropic.Anthropic()
panel.patch_anthropic(client)

# All Claude calls are now monitored automatically
```

## Decorators

```python
from agentmolt import monitor, budget, kill_switch

@budget("analyst", max_cost_usd=50.0)
@kill_switch("analyst")
@monitor("analyst")
def run_analysis():
    # Your agent code here — automatically monitored
    pass
```

## CLI

```bash
# Scan current directory for AI agent patterns
acp scan

# Show status of monitored agents
acp status

# Kill a rogue agent
acp kill marketing-bot --reason "unauthorized API spend"

# Check version
acp version
```

## Status Dashboard

Check all your agents at a glance:

```python
panel = ACP()
panel.register("agent-a", budget=AgentBudget(max_cost_usd=10.0))
panel.register("agent-b", budget=AgentBudget(max_cost_usd=5.0))

panel.log("agent-a", model="gpt-4o", tokens=2000, cost=1.50)
panel.log("agent-b", model="claude-3", tokens=500, cost=0.30)

for agent_id, state in panel.all_agents().items():
    status = "🟢 alive" if not state.killed else "🔴 killed"
    print(f"{agent_id}: {status} | ${state.total_cost_usd:.2f} | {state.total_calls} calls")
```

```
agent-a: 🟢 alive | $1.50 | 1 calls
agent-b: 🟢 alive | $0.30 | 1 calls
```

## Connect to AgentMolt Dashboard

For real-time monitoring, alerts, and team dashboards:

```python
panel = ACP(api_key="your-api-key")  # Get key at agentmolt.dev
```

Events are batched and sent every 5 seconds. Works offline — events are buffered and retried on failure.

## How It Works

1. **Register** agents with optional budgets
2. **Log** every LLM call (or auto-patch OpenAI/Anthropic)
3. **Budget check** on every call — kills agent if exceeded
4. **Kill switch** — manual or automatic, blocks all future calls
5. **Events** buffered and flushed to dashboard (if API key set)

No external dependencies required for local mode. Just `pip install agentmolt` and go.

## Requirements

- Python 3.9+
- No required dependencies for local mode
- Optional: `openai`, `anthropic` for auto-patching
- Optional: `httpx` for dashboard sync (included)

## License

MIT — built by [AgentMolt](https://agentmolt.dev)