Manual guard()

Use guard() directly when you need full control over execution flow — especially for tools that require approval polling.

Basic pattern

import gavrun
import time

gavrun.configure(
    api_key="gavrun_live_...",
    agent_manager_url="https://api.gavrun.ai",
)
client = gavrun.get_client()

def guarded_delete(user_id: str) -> str:
    result = client.guard(
        action="delete_user",
        execute=lambda: db.delete(user_id),
        tools=["delete_user"],
        prompt=f"Delete user {user_id} from the system.",
        session_id="sess_abc123",
        user_id="operator_001",
        user_role="admin",
        max_tokens=200,
    )

    if result.executed:
        return result.result

    if result.requires_human_review:
        approval_id = result.decision.get("approval_id")
        while True:
            status = client.get_approval_status(approval_id=approval_id)
            if status["status"] == "approved":
                return db.delete(user_id)
            elif status["status"] == "denied":
                raise PermissionError("Delete denied by reviewer")
            time.sleep(3)

    if result.denied:
        reason = result.decision["reasons"][0]["message"]
        raise PermissionError(f"Blocked by policy: {reason}")

guard_payload + guard_execution

For lower-level control, build the payload separately:

payload = client.guard_payload(
    action="send_email",
    tools=["send_email"],
    models=["gpt-4o-mini"],
    prompt="Send marketing email to customer list",
    max_tokens=500,
)

# Inspect or modify payload before sending
print(payload.tools, payload.prompt)

result = client.guard_execution(
    payload=payload,
    on_allow=lambda decision: mailer.send(to, subject, body),
)

check_or_raise

Simplest form — raises GavrunDecisionDenied on deny, returns decision on allow:

from gavrun.client import GavrunDecisionDenied

try:
    decision = client.check_or_raise(payload)
    # proceed with action
except GavrunDecisionDenied as e:
    print("Blocked:", e)