auctra (Python SDK)

Stage 0/1 Python client for issue, action.execute, consume_execution_lease, and evidence.verify. with_execution_lease is the protected consume-then-run helper. ALLOW alone is not permission to invoke the tool.

Requires Python 3.9+.

pip install auctra==0.3.10
# local dev: pip install -e packages/python-sdk

Quick start (with intent anchor)

Every governed action requires create_intent first, then pass the returned intent (id + anchor_token) on execute:

from auctra import Auctra

client = Auctra(api_key="auctra_...", base_url="https://app.auctra.tech")

agent_id = "your-agent-uuid"
expires_at = "2027-01-01T00:00:00Z"

client.authority.issue(
    subject=agent_id,
    capabilities=["send_payment"],
    expires_at=expires_at,
    max_amount=500,
    max_lifetime_actions=100,
    max_lifetime_amount=10_000,
    currency="USD",
)

created = client.create_intent(
    title="Pay matched vendor invoices",
    intent_type="payment",
    risk_level="high",
    max_risk_level="critical",
    allowed_action_types=["send_payment"],
    expires_at=expires_at,
)
intent = created["intent"]

preview = client.action.evaluate(
    agent_id=agent_id,
    action_type="send_payment",
    payload={"amount": 50, "currency": "USD"},
    intent=intent,
)

decision = client.action.execute(
    agent_id=agent_id,
    action_type="send_payment",
    payload={"amount": 50, "currency": "USD", "target": "vendor:acme"},
    intent=intent,
    action={
        "target": "vendor:acme",
        "description": "Net-30 invoice payment",
        "risk_level": "medium",
    },
)

print(decision["decision"])

from auctra import with_execution_lease

def invoke_tool(allowed):
    # side effect only after consume
    return allowed["action_request_id"]

if decision["decision"] == "allowed":
    with_execution_lease(client, decision, invoke_tool)

client.evidence.verify(payload=decision["evidence_payload"], evidence=decision["evidence"])

New-client gotcha

Sending only claimed_intent_id (without intent_anchor_token or the intent object) returns require_approval (low) or blocked (medium+) with a reason about the missing anchor. Pass intent= from create_intent, or set both claimed_intent_id and intent_anchor_token explicitly. Missing intent entirely on medium+ is now blocked.

See docs/integrations/intent-anchors.md.

Threat-engine helpers (Engine 03 + 12)

Lifetime budgets — cap total actions or spend across the delegation lifetime:

client.authority.issue(
    subject=agent_id,
    capabilities=["send_payment"],
    expires_at=expires_at,
    max_lifetime_actions=50,
    max_lifetime_amount=25_000,
    currency="USD",
)

Untrusted tool/MCP outputs — declare provenance on medium+ / tool-sourced / RAG paths so responses cannot authorize the next action (Authority Gate blocks without metadata.inputs):

from auctra import action_metadata_with_inputs, declare_tool_response_input

tool_input = declare_tool_response_input(
    tool_name="fetch_invoice",
    content_hash="sha256:…",
)

decision = client.action.execute(
    agent_id=agent_id,
    action_type="send_payment",
    payload={"amount": 50, "currency": "USD"},
    intent=intent,
    action={
        "target": "vendor:acme",
        "metadata": action_metadata_with_inputs(tool_input),
    },
)

Pass multiple inputs: action_metadata_with_inputs(a, b) or {"inputs": [a, b]} in action["metadata"].

Authority Gate responses — evaluate/execute may include gate_transcript (defense-in-depth layers) and threat_engines on the JSON body, aligned with @auctra/sdk@0.7.7. See docs/security/authority-gate.md.

Declare fetch/egress destinations via action["metadata"]["fetch"] / egress_host_allowlist, and MCP install trust via mcp_install + supply_chain_attestation (Engines 13–15) — same opt-in honesty model as tool attestation.

Public surface

declare_tool_response_input | action_metadata_with_inputs | InputProvenance
on_allowed | assert_authority_live
client.create_intent | list_intents
client.list_agents | create_agent | get_agent
client.list_api_keys
client.approve_action_request | reject_action_request
client.list_policies | create_policy | simulate_policy | publish_policy
client.get_authority_graph | get_authority_liveness | list_action_types | list_workload_identities
client.list_siem_endpoints | create_siem_endpoint | delete_siem_endpoint
client.list_incidents | open_incident | resolve_incident
client.list_compliance_packs | run_compliance_pack | list_compliance_runs
client.authority.issue | verify | delegate | revoke
client.action.evaluate | execute  (parent_action_id, execute_after)
client.get_action_request
client.evidence.verify