HaltState Documentation
HaltState is an action-control layer for AI agent governance. It sits between autonomous agents and sensitive business systems, evaluates tool calls against policy before execution, and records verifiable evidence for audit and incident response.
Start here
These docs are written for teams that are moving autonomous agents from chat into business operations. The important boundary is not whether an agent can generate a plan; it is whether the agent can perform a high-risk action such as creating a refund, authorizing a payment, exporting customer data, writing to a database, sending a customer message, or changing an order. HaltState gives that boundary a runtime control point.
The core pattern is simple: put a guard call immediately before the side effect, derive a stable idempotency key, send safe policy context, branch on the decision, execute only when allowed or later approved, and report the final outcome. This makes the enforcement path deterministic and testable. It also gives operators an evidence trail that can support incident response, internal controls, and governance programs without exposing customer payloads publicly.
The public retail refund agent is the reference workflow. It claims server-side ledger rows, asks HaltState for authority, writes simulated execution only for allowed or later-approved refunds, creates Proof Pack evidence, and sends sanitized live events to the public board. The same architecture applies to gift cards, loyalty credits, PII access, outbound communications, and production writes.
Use the quickstart when you need the first guarded action. Use the SDK pages when you are wiring a service. Use the guard, idempotency, approval, and exception pages when you are hardening retry behavior. Use the refund agent, ops API, policy, and Proof Pack pages when you need a fuller implementation model.
If you are evaluating HaltState as a buyer, start with the live control room and Proof Packs. If you are implementing it, start with the guard pattern and idempotency keys. If you are operating it, focus on approval lifecycle, ops APIs, redaction, and failure handling. The same pages are intentionally linked together so product, engineering, security, and compliance teams can discuss the same runtime facts rather than separate slideware.
Quickstart
Wrap a first high-risk tool call with the HaltState SDK.
Guard Pattern
Evaluate allow, deny, approval-required, and idempotent retry paths.
Approval Lifecycle
Route ambiguous or high-risk actions to human authority.
Proof Packs
Preserve verifiable evidence without exposing sensitive data.
Environment Variables
Configure tenant IDs, API keys, API origins, and worker runtime settings.
Refund Agent Example
Review the real server-side refund worker and ledger lifecycle.
Ops API Reference
Inspect live status, live feed, refund ledger, and process-once endpoints.
Policy Examples
Use deterministic policy packs for refunds, PII, payments, and database writes.
Getting Started
Introduction
HaltState is a runtime action-control layer for autonomous AI agents. It sits between agents and sensitive business systems, evaluates tool calls before execution, and records sanitized evidence after each decision.
How It Works
HaltState controls high-risk actions through a deterministic policy gate, optional human approval, execution reporting, and tamper-evident proof records.
Quickstart
Install the SDK, configure credentials, and wrap one business action with a HaltState guard.
Install
Install HaltState SDKs and prepare a safe environment for guarded service or worker execution.
Environment Variables
Use environment variables or a secrets manager to keep tenant IDs, API keys, API origins, and worker settings outside source code.
SDK Libraries
Python SDK
First-party Python SDK for server-side agents, scheduled workers, and async services.
TypeScript SDK
Use TypeScript for Node services, web backends, internal tools, and guarded business-action wrappers.
Go SDK
Use the Go SDK for low-latency backend services that need explicit guard checks.
Java SDK
Use the Java SDK for JVM services and enterprise backends.
Rust SDK
Use the Rust SDK for safety-critical workers and high-throughput services.
SDK Guides
Guard Pattern
The guard pattern places policy authority immediately before the side effect.
Decorators
Decorators provide a compact way to guard functions, but the underlying rule is unchanged: the side effect executes only after policy authority.
Idempotency Keys
Idempotency keys make retries, approval resumes, and crash recovery safe.
Approval Lifecycle
Approval flows route medium-risk actions to human authority while preserving deterministic worker behavior.
Exception Reference
SDK exceptions are control-flow signals that keep business code from executing without authority.
Patterns
Scripts vs Services
HaltState supports both scheduled scripts and long-running services, but their retry and reporting patterns differ.
Refund Agent Example
The retail refund agent is a real server-side worker pattern for guarded business actions.
Complete Example
A complete refund workflow combines idempotency, policy decisions, ledger transitions, Proof Packs, and public redaction.
Reference
Ops API Reference
Protected ops APIs expose status and operator controls, while the public live APIs expose sanitized evidence only.
Proof Pack Schema
Proof Packs preserve enough evidence to reconstruct a governed action while redacting sensitive payload details.
Policy Examples
Start with deterministic policies for the business actions most likely to create financial, privacy, or operational harm.
API Keys
API keys authenticate SDK clients, agents, workers, and protected operator tooling.
Why HaltState?
- Runtime control: intercept high-risk actions before execution.
- Low-latency enforcement: evaluate policies in under 50ms.
- Emergency controls: halt or quarantine sessions, agents, tools, or fleets.
- Verifiable evidence: record hash-verified Proof Packs for audit and incident response.
- Compliance support: provide operational evidence for governance programs aligned to SB 53 / TFAIA-style transparency obligations, EU AI Act programs, NIST AI RMF, ISO/IEC 42001, and SOC 2 control narratives.