UprelicStrom

Agent guard: Regeln in einfachen Worten für Ihren KI-Agenten

Prüfen Sie die Tool-Aufrufe Ihres Agenten, deren Ergebnisse und seine Antworten gegen Regeln, die Sie als Sätze schreiben.

·4 Min. Lesezeit

Ein KI-Agent entscheidet selbst, welche Tools er aufruft und was er dem Nutzer sagt. Meistens ist das gewollt. Manchmal erstattet er aber zu viel Geld, gibt Daten weiter, die er nicht weitergeben sollte, oder verspricht etwas, dem niemand zugestimmt hat. Agent guard gibt Ihnen Hooks an drei Stellen im Ablauf des Agenten, an denen jeder Schritt gegen Ihre Regeln geprüft wird, bevor er wirksam wird.

So funktioniert es

Regeln. Sie schreiben jede Regel als Satz, zum Beispiel „Block refunds above 500 unless the user's role is manager.“ Sie legen fest, für welche Tools sie gilt und ob sie blockieren oder vorerst nur melden soll. Regeln sind in Ihrem Konto gespeichert. Sie können sie also ändern, ohne den Agenten zu ändern oder neu zu deployen.

Prüfungen. Ihr Agent schickt, was er gleich tun will oder gerade zurückbekommen hat, an einen Endpunkt: POST /v1/guard/check. Für jede Regel, die zutrifft, antwortet Strom, wie wahrscheinlich es ist, dass sie verletzt wird, und sagt Ihnen, ob es weitergehen kann. Es gibt drei Stellen im Ablauf des Agenten, an denen Sie prüfen können:

  • bevor ein Tool läuft (before_tool),
  • nachdem ein Tool gelaufen ist, bevor der Agent das Ergebnis sieht (after_tool),
  • bevor eine Antwort an den Nutzer geht (before_reply).

Eine Regel gehört zu einer dieser Stufen. Eine Regel im Modus enforce blockiert, wenn sie greift. Eine Regel im Modus observe blockiert nie; sie meldet nur would_block. So sehen Sie zuerst, was sie abfangen würde.

Ein Beispiel

Ein Support-Agent für einen Onlineshop hat zwei Tools: lookup_order und refund. Wir geben ihm drei Regeln:

Regel Stufe Tools Modus
refund-limit: „Block refunds above 500 unless the user's role is manager.“ before_tool refund enforce
no-card-numbers: „Block results that contain a full card number.“ after_tool lookup_order enforce
no-promised-dates: „Block replies that promise the customer a date for a refund or delivery.“ before_reply observe

Eine Regel wird mit einer Anfrage angelegt:

curl https://api.uprelic.com/v1/guard/rules \
  -H "Authorization: Bearer $UPRELIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "refund-limit",
    "text": "Block refunds above 500 unless the user’s role is manager.",
    "stage": "before_tool",
    "tools": ["refund"],
    "mode": "enforce"
  }'

Das Support-Team des Shops beantwortet Kundenanfragen mit dem Agenten. Eine Mitarbeiterin, angemeldet mit der Rolle support_agent, gibt ihm die Nachricht eines Kunden: „I want a refund for order A1.“ Die Antworten unten sind echte Antworten der API, gekürzt.

1. Der Agent sucht die Bestellung

Bevor lookup_order läuft, prüft der Agent den Aufruf:

{"action": "lookup_order", "params": {"order_id": "A1"}, "context": {"role": "support_agent"}}

Keine before_tool-Regel gilt für lookup_order, also lautet die Antwort allow, ohne dass eine Regel ausgewertet wird. Eine solche Prüfung ist kostenlos.

2. Die Bestellung kommt mit einer Kartennummer zurück

Das Bestellsystem liefert mehr als es sollte:

{"order_id": "A1", "total": 800, "status": "delivered", "card": "4111 1111 1111 1111"}

Bevor der Agent es sieht, wird das Ergebnis geprüft. Es geht als result mit derselben action und denselben params mit:

{
  "decision": "block",
  "rules": [
    {"id": "no-card-numbers", "probability": 0.92, "threshold": 0.9,
     "mode": "enforce", "matched": true}
  ]
}

Der Agent bekommt das Ergebnis nicht. Stattdessen bekommt er den Text der Regel: „Block results that contain a full card number.“ Dieselbe Bestellung, in der nur die letzten vier Ziffern der Karte stehen, bekommt eine Wahrscheinlichkeit von 0,07 und wird durchgelassen.

Das Tool ist trotzdem gelaufen. Eine Prüfung nach einem Tool kann verhindern, dass sein Ergebnis beim Agenten ankommt, aber nicht rückgängig machen, was das Tool getan hat. Tools, die etwas verändern, prüfen Sie deshalb, bevor sie laufen.

3. Der Agent will 800 erstatten

{"action": "refund", "params": {"order_id": "A1", "amount": 800}, "context": {"role": "support_agent"}}
{
  "decision": "block",
  "rules": [
    {"id": "refund-limit", "probability": 0.94, "threshold": 0.9,
     "mode": "enforce", "matched": true}
  ]
}

Die Erstattung läuft nicht, und der Agent erfährt, warum. Derselbe Aufruf mit "role": "manager" bekommt eine Wahrscheinlichkeit von 0,02 und wird durchgelassen.

Die Rolle steht in context. Ihre Anwendung füllt sie aus dem angemeldeten Nutzer, nicht aus etwas, das das Modell geschrieben hat. Könnte das Modell die Rolle setzen, könnte es sich auch selbst zum Manager machen.

4. Der Agent schreibt eine Antwort

Der Agent entwirft: „Refunds above 500 need a manager's approval. I've passed your request on, and you'll have your money back by Friday.“

Niemand hat Freitag zugesagt. Die Antwort wird mit response geprüft (und der Nachricht des Nutzers als request):

{
  "decision": "would_block",
  "rules": [
    {"id": "no-promised-dates", "probability": 0.94, "threshold": 0.9,
     "mode": "observe", "matched": true}
  ]
}

Die Regel ist noch im Modus observe, also wird die Antwort gesendet. Dieselbe Antwort ohne „by Friday“ bekommt 0,02.

5. Die Regel einschalten

Nach ein paar Tagen listen wir auf, was die Regel für Antworten blockiert hätte:

curl "https://api.uprelic.com/v1/guard/checks?decision=would_block" \
  -H "Authorization: Bearer $UPRELIC_API_KEY"

Jede Prüfung kommt mit der Antwort, der Nachricht des Nutzers und der Wahrscheinlichkeit jeder Regel zurück. Passen die Treffer, stellen wir die Regel mit PUT /v1/guard/rules/no-promised-dates auf enforce. Passen sie nicht, formulieren wir die Regel um oder erhöhen ihren Schwellenwert und beobachten weiter.

Was es gekostet hat

Vier Prüfungen, drei davon mit je einer Regel: 3 ausgewertete Regeln zu 0,01 $ pro 1.000, also 0,00003 $. Jede Prüfung dauerte auf dem Server 30 bis 40 ms.

In Python

Mit dem Python-SDK übernimmt ein Decorator die Prüfungen:

import uprelic

client = uprelic.Uprelic()

@client.guard("refund", context=lambda: {"role": current_user.role})
def refund(order_id, amount):
    ...

@client.guard("lookup_order", check_result=True)
def lookup_order(order_id):
    ...

try:
    refund("A1", amount=800)
except uprelic.Blocked as blocked:
    tool_result = str(blocked)  # give this to the agent instead

Stärken

  • Regeln sind Sätze. Wer die Richtlinie kennt, aber nicht den Code, kann sie schreiben und ändern, ohne Deploy.
  • Es funktioniert mit jedem Agenten. Es ist ein HTTP-Aufruf an drei Stellen im Ablauf, egal welches Framework oder Modell den Agenten betreibt.
  • Sie können eine Regel testen, bevor sie blockiert. Im Modus observe läuft eine Regel auf echtem Verkehr und zeichnet auf, was sie blockiert hätte.
  • Es ist schnell und günstig. Eine Prüfung dauert einige zehn Millisekunden und kostet 0,01 $ pro 1.000 Regeln.

Schwächen

  • Es ist ein Modell, also kann es sich irren. Es wird manchmal einen Fall übersehen oder einen harmlosen blockieren. Exakte Grenzen wie „Betrag über 500“ sind in Ihrem eigenen Code sicherer. Regeln lohnen sich vor allem für das, was Code schlecht prüfen kann, etwa was eine Antwort verspricht.
  • Eine Prüfung sieht nur, was Sie schicken. Sie kennt keine früheren Aufrufe. Eine Regel wie „höchstens drei Erstattungen pro Tag“ braucht also die Anzahl in context.
  • Jede Prüfung kostet einen Roundtrip, an jeder Stelle, an der Sie prüfen. In einer langen Folge von Tool-Aufrufen summiert sich das.

Ausprobieren

  • Die Agent-guard-Demo führt einen simulierten Agenten in der Konsole durch diese Prüfungen, ganz ohne Code.
  • Die Dokumentation beschreibt jedes Feld und jeden Fehler.
  • Das Python-SDK: pip install uprelic.

Fragen und Feedback: support@uprelic.com.

Mehr aus dem Blog