Skip to main content

Introduction

Learn how to control what runs before it runs using deterministic in-process policies across APIs, workflows, and AI agents.

Welcome to Actra — the policy engine for runtime governance, admission control, approvals, and AI tool safety.

This section helps you go from zero to production-ready policy enforcement using the fastest learning path.

Whether you are integrating Actra into:

  • Python services
  • JavaScript / TypeScript apps
  • FastAPI or Express
  • background workers
  • CI/CD pipelines
  • MCP servers
  • AI agents

this section gives you the core mental model first.

What You’ll Learn​

By the end of this section, you’ll know how to:

  • define a schema
  • write policy rules
  • compile policies
  • protect functions and handlers
  • inject actor identity
  • inject business state
  • debug decisions
  • test policies in CI
  • roll out safely with audit mode

Core Mental Model​

Incoming action
 -> Resolve actor
 -> Resolve snapshot
 -> Evaluate policy
 -> Allow / Block / Require approval

Everything in Actra revolves around three domains:

  • action → what is being attempted
  • actor → who is attempting it
  • snapshot → current world or business state

Policies make deterministic decisions from these inputs.

Follow this sequence for the fastest onboarding experience.

1) Basic Refund Example​

Start with the first end-to-end example.

Learn:

  • schema basics
  • blocking rules
  • runtime admission control
  • exceptions

2) Runtime Context​

Then understand the two most important resolvers:

  • Actor Resolver
  • Snapshot Resolver

These connect Actra to your real identity and business state.

3) Explain & Debugging​

Next, learn how to inspect decisions.

Use:

  • policy.explain()
  • runtime.explain()
  • runtime.explain_call()

This is critical before production rollout.

4) Observability & Audit​

Before enforcement, use:

  • decision observers
  • structured logs
  • metrics
  • audit() shadow mode

This builds rollout confidence.

5) Testing Policies​

Finally, lock policy behavior into CI.

Use:

  • assert_effect()
  • policy hash checks
  • boundary tests
  • approval tests

This makes governance changes safe.

Best First Use Cases​

If you’re evaluating where to start, these are the strongest Actra workflows:

  • refund approvals
  • deploy gates
  • AI tool governance
  • MCP tool controls
  • finance approvals
  • production safety checks
  • tenant isolation
  • destructive action protection

Python + JavaScript Examples​

All examples in this section are organized as:

single scenario page + language tabs

This helps you learn the same governance workflow across SDKs.

Typical structure:

  • Python
  • JavaScript

on the same page.

Production Rollout Strategy​

The safest rollout path is:

Examples -> Explain -> Audit -> Tests -> Admit

This sequence dramatically reduces production risk.

Where to Go Next​

Recommended first page:

Installation

Then continue in the recommended learning path above.