airg-client 0.3.2

Python client for the AI Runtime Governor – runtime AI-agent governance service

airg-client

Python client for the AI Runtime Governor – a runtime governance layer for AI agents.

The Governor evaluates every tool invocation against configurable policies and returns an allow / block / review decision before the tool executes.

Installation

pip install airg-client

Quick start

from airg import AIRG

client = AIRG()

decision = client.evaluate(
    tool="shell_exec",
    args={"command": "ls -la /tmp"},
    context={"session_id": "abc-123"},
)
print(decision["decision"])      # "allow" | "review"
print(decision["risk_score"])    # 0.0 – 1.0
print(decision["explanation"])

Configuration

Environment variable	Description
GOVERNOR_URL	Base URL of the Governor service
GOVERNOR_API_KEY	API key (airg_…)

Or pass them explicitly:

client = AIRG(api_key="airg_...", base_url="https://...")

API

AIRG(*, api_key=None, base_url=None, timeout=10.0)

Create a client. Reads GOVERNOR_API_KEY and GOVERNOR_URL from environment variables when not provided.

client.evaluate(tool, args, context=None) → dict

Evaluate a tool call. Returns the decision dict:

{
    "decision": "allow",        # "allow" | "block" | "review"
    "risk_score": 0.15,
    "explanation": "Low-risk read operation",
    "policy_ids": ["shell-guard"],
    "modified_args": None,
}

Raises BlockedError if the decision is "block".

client.scan(text, agent_id=None, session_id=None, context=None) → dict

Scan agent output for threats before sending to users.

client.verify(action_id, tool, result, context=None) → dict

Post-execution verification. Raises VerificationError on violations.

client.ingest_spans(spans) → dict

Batch-ingest agent trace spans.

client.list_traces(**filters) → list

List traces with optional filters (agent_id, session_id, has_blocks, limit, offset).

client.get_trace(trace_id) → dict

Fetch full trace detail.

client.delete_trace(trace_id) → dict

Delete all spans for a trace.

Exceptions

Exception	Description
AIRGError	Base exception
BlockedError	Governor blocked the action
ReviewRejectedError	Human reviewer rejected
ReviewExpiredError	Review timed out
VerificationError	Post-execution violation

Requirements

• Python ≥ 3.9
• httpx ≥ 0.24.0

License

MIT — see LICENSE.