AgentGuard SDK Reference
Evaluate agent tool calls against security policies before they execute. Provides sync (ActionGuardClient) and async (AsyncActionGuardClient) clients.
This page is for the standalone AgentGuard integration. If you are using the VirtueGateway, AgentGuard is applied automatically — no separate client setup is needed. Go to the SDK integration overview and follow Integrate with VirtueGateway instead.
Installation
pip install agentsuite-sdk
Configuration
| Variable | Description |
|---|---|
VIRTUE_API_KEY | VirtueAI API key (sk-vai-...) |
ACTION_GUARD_POLICY_ID | Policy set ID (agp_...) — created in the AgentGuard dashboard |
ACTION_GUARD_BASE_URL | Optional; API base URL (defaults to https://api.actionguard.ai) |
Quick Start
from agentsuite import ActionGuardClient
with ActionGuardClient() as guard:
result = guard.actions.guard_query(
query="Tool: delete_file, Args: {'path': '/etc/passwd'}",
)
if not result.allowed:
print(f"Blocked: {result.explanation}")
print(f"Violations: {result.violations}")
Use AsyncActionGuardClient with await for async frameworks.
Stateless vs Stateful
Stateless (guard_query) — evaluate a single action with no context. Best for most use cases.
result = guard.actions.guard_query(
query="Tool: delete_user, Args: {'username': 'admin'}",
fast_mode=True, # lower latency
)
Stateful (guard) — pass the full session history for context-aware decisions.
result = guard.actions.guard(
session_id="user-123",
session_history={
"session_info": {"gateway_id": "my-gateway"},
"trajectory": [
{"role": "user", "state": "list all users"},
{
"role": "agent",
"action": "Tool: list_users, Args: {}",
"metadata": {"tool_name": "list_users", "tool_params": {}},
},
],
},
)
Client Setup
Use ActionGuardClient for sync frameworks (ADK, LangChain, Strands) and AsyncActionGuardClient for async frameworks (OpenAI, Claude, MS365):
from agentsuite import ActionGuardClient # sync
from agentsuite import AsyncActionGuardClient # async
guard = ActionGuardClient(
api_key="sk-vai-...", # or set VIRTUE_API_KEY env var
policy_id="agp_...", # or set ACTION_GUARD_POLICY_ID env var
)
Result Fields
| Field | Type | Description |
|---|---|---|
allowed | bool | Whether the action is permitted |
explanation | str | Reason for the decision |
violations | list | Policy rules violated |
warnings | list | Non-blocking warnings |
threat_category | str | Category of detected threat |
blocking_mode | str | Block or monitor mode |
Error Handling
All SDK errors are subclasses of GuardError:
| Exception | When raised |
|---|---|
GuardConfigError | Missing or invalid api_key / policy_id at construction |
GuardAPIStatusError | API returned a non-2xx HTTP response; carries status_code and response |
GuardTimeoutError | Request timed out |
GuardConnectionError | Server unreachable (DNS, network, bad URL) |
Catch GuardError to handle any error in one place, or use specific subclasses for finer control.
Framework Integration
For wiring guard_query into your framework's hook system, see: