HaltState AI: Quickstart Guide

Get HaltState up and running in under 5 minutes.

1. Install the SDK

pip install haltstate-sdk

2. Get Your Credentials

Sign up at the HaltState Dashboard to get your: - Tenant ID - Your organization identifier - API Key - Starts with hs_

3. Use the Guard Pattern

The guard() context manager is the recommended way to gate agent actions:

from haltstate import HaltStateClient, ApprovalPending, ActionDenied
import sys

client = HaltStateClient(
    tenant_id="your-tenant-id",
    api_key="hs_your_api_key"
)

try:
    with client.guard(
        action="database.delete",
        params={"table": "users", "id": 123},
        idempotency_key="delete-user-123-2026-01-05"
    ) as permit:
        # This block ONLY executes if approved
        delete_user(123)
        print(f"Approved by: {permit.approver}")

except ApprovalPending as e:
    # Action requires human approval - exit gracefully
    print(f"Awaiting approval: {e.approval_id}")
    sys.exit(0)  # Script exits, scheduler retries later

except ActionDenied as e:
    # Policy denied the action
    print(f"Action denied: {e}")
    sys.exit(1)

What Just Happened?

Guard checks policy - HaltState evaluates if the action is allowed
Three possible outcomes:
✅ Allowed - Guard block executes immediately
⏳ Approval Required - ApprovalPending raised, human reviews in dashboard
❌ Denied - ActionDenied raised, policy blocked it
Idempotency key - If you retry with the same key after approval, it remembers and executes