Hook (Client) and SDK Reference

Below, we use Action Guard as an example to show how to write Hook (Client) function with our agentsuite-sdk.

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 Action Guard 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.