Authensor Python SDK guide

The Authensor Python SDK (authensor) brings the same policy enforcement, content scanning, and audit trail capabilities to Python AI agents. It shares the same policy format and evaluation logic as the TypeScript SDK.

Installation

pip install authensor

Creating a guard

from authensor import create_guard

# From a YAML file
guard = create_guard(policy_path="./policy.yaml")

# From a dict
guard = create_guard(policy={
    "version": "1",
    "rules": [
        {"tool": "*", "action": "allow"}
    ]
})

# Connected to the control plane
guard = create_guard(
    control_plane="https://your-server.com",
    api_key=os.environ["AUTHENSOR_API_KEY"],
)

Evaluating tool calls

decision = guard("file.delete", {"path": "/data/report.csv"})

if decision.action == "block":
    print(f"Blocked: {decision.reason}")
elif decision.action == "escalate":
    approval = wait_for_approval(decision.receipt.id)
    if approval.granted:
        execute_tool("file.delete", {"path": "/data/report.csv"})
else:
    execute_tool("file.delete", {"path": "/data/report.csv"})

Enabling Aegis

guard = create_guard(
    policy_path="./policy.yaml",
    aegis={"enabled": True, "threshold": 0.7},
)

Enabling Sentinel

def on_alert(alert):
    send_notification("sentinel", alert)

guard = create_guard(
    policy_path="./policy.yaml",
    sentinel={
        "enabled": True,
        "window_size": 60_000,
        "on_alert": on_alert,
    },
)

Using as a decorator

The Python SDK provides a decorator for wrapping functions:

from authensor import guarded

@guarded(tool_name="email.send", policy_path="./policy.yaml")
def send_email(to: str, subject: str, body: str):
    # This function only runs if the policy allows it
    mailer.send(to=to, subject=subject, body=body)

Context manager

For batch operations, use the context manager to share a single guard instance:

from authensor import AuthensorSession

with AuthensorSession(policy_path="./policy.yaml") as session:
    session.guard("file.read", {"path": "/data/input.csv"})
    session.guard("file.write", {"path": "/data/output.csv", "content": "..."})

    # All receipts are available
    receipts = session.get_receipts()
    assert session.verify_chain()

Type hints

The SDK is fully typed. All return types and parameters have type annotations:

from authensor.types import PolicyDecision, Receipt

decision: PolicyDecision = guard("tool.name", {"key": "value"})
receipt: Receipt = decision.receipt

Integration with async frameworks

For async Python agents, use the async guard:

from authensor import create_async_guard

guard = create_async_guard(policy_path="./policy.yaml")
decision = await guard("tool.name", {"key": "value"})

This is useful when connecting to the control plane, where policy fetching and receipt storage involve network I/O.