agentguard-kit

AgentGuard

Stop your agents from silently burning API credits.

AgentGuard is a lightweight runtime guard that detects loops, tracks repeated calls, and shows how many tokens your agent is wasting — in real time.

pip install agentguard-kit

---

⚠️ The Problem

LLM agents don't fail loudly.

They do this instead:

search("python error")
→ read_file("log.txt")
→ search("python error")
→ read_file("log.txt")
→ search("python error")

No crash. No exception. Just silent repetition… and a growing API bill.

---

✅ The Solution

Wrap your tools. Run your agent. Let AgentGuard track what's actually happening.

from agentguard import Guard
from agentguard.decorators import track

g = Guard()
g.start()

@track
def search(query):
    return f"results for {query}"

for step in ["a", "b", "a", "b"]:
    search(step)

print(g.report())

Example output:

AgentGuard Report

Verdict: BAD (Loop Detected)
Reason: Repeating step pattern detected
Severity: High
Confidence: 0.90

---

Total Calls: 4
Wasted Calls: 2
Waste Ratio: 50%

---

Signals:
- Loop Detected: Yes
- High Waste: No

---

Token Usage:

Total Tokens: 200
Wasted Tokens: 100
Token Waste: 50%

---

Suggestions:
- Possible infinite loop detected — verify stopping conditions
- Check repeated tool inputs
- Add guard conditions.

---

⚠️ About Repeated Calls

AgentGuard detects repeated and looping behavior based on execution patterns.

However, not all repetition is a bug.

Valid cases include:

• retries (network/API failures)
• pagination or iteration
• multi-step workflows

AgentGuard does NOT assume intent.

It highlights high-level inefficiency signals — you decide whether to act.

---

🧠 What It Detects

• Consecutive loops (hard stuck behavior)
• Frequent loops (error prone exploration)
• Repeated tool calls (waste ratio)
• Token waste (explicit or estimated)

---

⚙️ Token Tracking

AgentGuard works in two modes:

1. Automatic (no setup):

   search("hello")
   

   Uses a deterministic estimate:

   tokens ≈ len(payload) // 4
   

2. Explicit (recommended):

   search("hello", tokens=120)
   

   Uses real token usage from your LLM provider.

---

🧪 Real-World Integrations

Example 1 — Autopilot Loop (no tokens passed):

from agentguard import Guard
from agentguard.decorators import track

g = Guard()
g.start()

@track
def fallback_search(query):
    return f"retrying {query}"

for _ in range(3):
    fallback_search("python error")

print(g.report())

Example 2 — OpenAI Integration (real tokens):

from agentguard import Guard
from agentguard.decorators import track
from openai import OpenAI

client = OpenAI()

g = Guard()
g.start()

@track
def ask_llm(prompt, tokens=None):
    return prompt

def call_llm(prompt):
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}]
    )

    total_tokens = response.usage.total_tokens

    return ask_llm(prompt, tokens=total_tokens)

call_llm("Explain python loops")
call_llm("Explain python loops")
call_llm("Explain python loops")

print(g.report())

---

🎯 Why Use AgentGuard?

Because your agent might be:

• Looping without you noticing
• Repeating expensive calls
• Wasting 50–80% of tokens silently

AgentGuard makes that failure visible.

---

Installation

pip install agentguard-kit

---

Minimal Usage

g = Guard()
g.start()

@track
def tool(x):
    return x

tool("a")
tool("a")

print(g.decision())
print(g.suggest())