API Reference

Complete reference for the quint-agent Python SDK.

quint_agent.init()

Initialize the global Quint client. Must be called before any @guard() calls. Idempotent — calling twice returns the same client.

def init(
    *,
    api_key: str | None = None,        # or QUINT_API_KEY env var
    endpoint: str | None = None,        # default: https://api.quintai.dev/v1/sdk/events
    policy: Policy | dict | str | None = None,  # YAML file path, dict, or Policy object
) -> Client

Parameter	Default	Description
api_key	$QUINT_API_KEY	SDK API key (starts with qak_)
endpoint	https://api.quintai.dev/v1/sdk/events	Cloud ingest endpoint
policy	Built-in default	Security policy (YAML path, dict, or Policy)

Raises: QuintConfigError if api_key is missing.

@quint_agent.guard()

Decorator that wraps a tool function with capture and policy enforcement.

def guard(*, name: str | None = None) -> Callable

Parameter	Default	Description
name	Function name	Override the tool name in telemetry

Works with both sync and async functions:

@quint_agent.guard()
def sync_tool(path: str) -> str: ...

@quint_agent.guard(name="custom_name")
async def async_tool(url: str) -> dict: ...

Raises: ToolBlockedError if the call violates policy.

Client

The underlying client object. Usually you don’t interact with it directly — init() creates a global singleton.

class Client:
    api_key: str
    endpoint: str
    policy: Policy
    policy_engine: PolicyEngine
    transport: Transport
    sdk_version: str

Policy

A collection of rules evaluated against each tool call.

class Policy:
    rules: list[Rule]

Rule

A single policy rule.

class Rule:
    name: str
    action: Action          # Action.BLOCK or Action.ESCALATE
    reason: str
    conditions: list[Matcher]

Decision

The result of evaluating a tool call against the policy.

class Decision:
    action: Action          # ALLOW, BLOCK, or ESCALATE
    matched_rule: Rule | None
    reason: str | None

Exceptions

class QuintError(Exception):
    """Base class for all quint-agent exceptions."""

class QuintConfigError(QuintError):
    """Raised when init() is called with invalid configuration."""

class ToolBlockedError(QuintError):
    """Raised when @guard() blocks a tool call due to policy."""
    tool_name: str
    rule_name: str
    reason: str

Environment variables

Variable	Description
QUINT_API_KEY	SDK API key (alternative to passing api_key to init())
QUINT_ENDPOINT	Override the cloud endpoint URL
QUINT_POLICY	Path to a YAML policy file

Transport

Events are batched in-memory and flushed asynchronously every 500ms (or when the buffer reaches 100 events). The transport is non-blocking — @guard() never waits for the HTTP POST to complete.

@guard() call → emit() → in-memory queue → background flush → POST /v1/sdk/events
                                                                    ↓
                                                             Quint cloud

Failed flushes retry with exponential backoff (1s, 2s, 4s, max 30s). After 5 consecutive failures, events are dropped with a stderr warning.