SDK Quickstart

Connect your AI agents to Zabta in minutes. Govern every action with policy-as-code.

Quick Start

Govern your AI agents in two lines of code:

python

import zabta
zabta.init("zbt_your_api_key")

# That's it. Your OpenAI/Anthropic/LangChain calls are now governed.
# Every LLM interaction is checked against your active policies.

When you call zabta.init(), Zabta automatically intercepts calls to OpenAI, Anthropic, and LangChain. Every LLM interaction is checked against your governance policies before it executes.

Auto-detection: Zabta scans message content for PII patterns, sensitive keywords, and decision-making language to automatically set context flags like has_pii, is_irreversible, and generates_content.

Manual Mode

For fine-grained control, use the client directly:

python

from zabta import ZabtaClient

client = ZabtaClient(
    api_key="zbt_your_api_key_here",
    base_url="https://api.zabta.ai"
)

# Check before acting
result = client.evaluate("send_email", "customer_data", {"has_pii": True})
if result.allowed:
    send_email(customer)
elif result.escalated:
    queue_for_approval(result.reason)
else:
    log_denied(result.reason)

Installation

bash

pip install zabta

# With auto-instrumentation for specific providers:
pip install zabta[openai]      # OpenAI support
pip install zabta[anthropic]   # Anthropic support
pip install zabta[all]         # All providers

The base package has no LLM dependencies. Install extras for auto-instrumentation.

Authentication

Every agent gets its own API key when you create it in the dashboard. The key format is zbt_ followed by a random string. See the API Keys guide for generating, revoking, and securing your keys.

Pass the key as api_key to ZabtaClient
The SDK sends it as an X-API-Key header
Each API key is scoped to one agent — the policy engine evaluates against that agent's tenant policies

python

from zabta import ZabtaClient

# API key is generated when you create an agent in the dashboard
client = ZabtaClient(
    api_key="zbt_hHnZjve-SSwtS8xu...",  # starts with zbt_
    base_url="https://api.zabta.ai"
)

# The SDK sends: Authorization: Bearer zbt_...
# Each API key is scoped to one agent

Core Methods

`client.evaluate(action, resource, context)`

The primary governance check. Call this before your agent takes an action.

Parameters:

action (str) — what the agent wants to do, e.g. "send_email", "delete_record"
resource (str) — what it's acting on, e.g. "customer_data"
context (dict, optional) — additional context that policies evaluate against

python

result = client.evaluate(
    action="send_email",         # what the agent wants to do
    resource="customer_data",    # what it's acting on
    context={                    # triggers specific policies
        "has_pii": True,
        "is_irreversible": False,
    }
)

print(result.decision)   # "allow", "deny", or "escalate"
print(result.allowed)    # True / False
print(result.reason)     # "PII detected — requires human approval"
print(result.policy)     # "PII Guardian"
print(result.citation)   # "GDPR Art. 5"
print(result.risk_tier)  # "medium"

`client.is_allowed(action, resource)`

Quick boolean check — returns True if allowed, False otherwise.

python

if client.is_allowed("send_email", "customer_data"):
    send_email(customer)
else:
    print("Action not allowed")

`@client.governed(action, resource, context)`

Decorator that wraps a function with automatic policy evaluation.

python

@client.governed(
    action="process_refund",
    resource="payment",
    context={"is_irreversible": True}
)
def process_refund(order_id, amount):
    stripe.refunds.create(charge=order_id, amount=amount)

# If policy says ALLOW → function runs
# If policy says DENY  → raises GovernanceError
# If policy says ESCALATE → raises EscalatedError

`client.log_action(action, resource, outcome)`

Log an action that already happened (monitoring mode — no enforcement).

python

client.log_action(
    "processed_ticket",
    "support_ticket_123",
    outcome="success"
)

For a complete list of all methods and types, see the SDK Reference.

Integration Examples

A simple Python agent that checks policy before accessing customer data:

python

from zabta import ZabtaClient

client = ZabtaClient(api_key="zbt_...", base_url="https://api.zabta.ai")

def handle_customer_request(request):
    # Check if we can access customer data
    result = client.evaluate("read", "customer_profile", {"has_pii": True})

    if result.denied:
        return f"Action blocked: {result.reason} ({result.citation})"

    if result.escalated:
        return f"Needs approval: {result.reason}"

    # Allowed — proceed
    customer = db.get_customer(request.customer_id)
    return generate_response(customer, request.query)

Policy Context Reference

These context keys trigger specific policies when passed to client.evaluate(). Universal policies (PII Guardian, Human Approval Gate, etc.) are always active. Jurisdiction and sectoral policies only fire when their pack is activated.

python

# Context keys that trigger specific policies
{"has_pii": True}                   # PII Guardian → ESCALATE
{"is_irreversible": True}           # Human Approval Gate → ESCALATE
{"generates_content": True}         # EU Watermarking → DENY (if EU active)
{"injection_detected": True}        # Prompt Injection Shield → DENY
{"has_automated_decision": True}    # ADM Safeguards → ESCALATE
{"is_high_impact_system": True}     # Risk Assessment → ESCALATE

Context Key	Policy Triggered	Decision	Citation
has_pii	PII Guardian	ESCALATE	GDPR Art. 5
is_irreversible	Human Approval Gate	ESCALATE	EU AI Act Art. 14
generates_content	EU Watermarking	DENY	EU AI Act Art. 50
injection_detected	Prompt Injection Shield	DENY	OWASP ASI01
kill_switch_active	Kill Switch	DENY	OWASP ASI08
has_automated_decision	ADM Safeguards (UK/AU/BR)	ESCALATE	Varies by jurisdiction
is_customer_facing	Governance Framework policies	ALLOW (logged)	Varies
is_high_impact_system	Risk Assessment policies	ESCALATE	Varies
makes_decisions_about_individuals	Bias Mitigation policies	ESCALATE	Varies
is_irreversible	Agentic AI Controls (SG)	ESCALATE	IMDA MGF 2026
processes_personal_data_at_scale	DPIA Requirement (UK)	ESCALATE	UK GDPR Art. 35

Learn more about how policies are evaluated in the Policy Engine documentation, or explore all supported jurisdictions.

Error Handling

The SDK provides specific exception types for each governance outcome:

python

from zabta import ZabtaClient, GovernanceError, EscalatedError

client = ZabtaClient(api_key="zbt_...", base_url="https://api.zabta.ai")

try:
    result = client.evaluate(
        "delete", "customer_record",
        {"has_pii": True, "is_irreversible": True}
    )
except GovernanceError as e:
    print(f"Denied: {e.reason} — {e.citation}")
except EscalatedError as e:
    print(f"Needs approval: {e.reason}")
    queue_for_human_review(e.details)
except ConnectionError:
    # Zabta is unreachable. The exception is the signal — there is no
    # silent default. Decide within your own risk tolerance, or use
    # is_allowed() elsewhere, which errs toward denial automatically.
    print("Zabta unavailable — action not evaluated")

Recommendation: Use is_allowed() when a boolean is all you need — it catches connectivity failures and returns False, so an outage never reads as permission. For evaluate() / check(), catch ConnectionError explicitly rather than letting it propagate into your agent's normal control flow.

FAQ

What happens if Zabta is down?

Behavior is per-method, and none of it is a silent allow. evaluate() and check() raise ConnectionError (or RetryExhaustedError after retries) — the exception is the signal, and you decide how to handle it. is_allowed(), the boolean convenience method, catches any exception and returns False: it errs toward denial by design, so an outage never reads as "allowed."

How fast is evaluation?

~500ms on cached requests, ~2.5s on cold start. The policy cache has a 5-minute TTL. For latency-sensitive agents, use is_allowed() with a timeout.

Can I use this with JavaScript/TypeScript agents?

Not yet. Use the REST API directly. A JS SDK is on the roadmap.

Do I need to call evaluate() for every action?

Only for actions that could be risky. Read-only actions on public data will almost always return ALLOW. Focus on write operations, PII access, and irreversible actions.

How do I add custom policies?

Go to Policies in the dashboard, click "Create Policy", define conditions and access level. Custom policies are evaluated alongside universal and jurisdiction policies.

This governs what my agent does. What governs the API keys it holds?

That's a separate concern — the Zabta Broker. It's a local daemon that vaults your provider credentials and issues short-lived, policy-checked leases at the moment of use, so secrets never sit in an env file. See the Broker Quickstart.