Python SDK

caracalai-sdk is the main Python package for async agent lifecycle, delegation, Gateway routing, and ASGI context propagation.

Install

pip install caracalai-sdk

The package requires Python >=3.12.

Connect and Configure

API	Use it when
`Caracal()`	Auto-detect a runtime profile or environment variables.
`Caracal.from_env()`	Load only from `CARACAL_*` environment variables.
`Caracal.from_config(path)`	Load a Console-generated `caracal.toml`.
`Caracal.from_client_secret(...)`	Build a client that refreshes application subject tokens through STS.

from caracalai import Caracal

caracal = Caracal()

Core methods

Method	Purpose
`async with caracal.spawn(...)`	Create and bind an agent session; pass `grant=Grant.narrow(...)` to bound the child’s authority.
`await caracal.spawn_service(...)`	Start a long-lived service agent; returns a handle with `heartbeat()` and `aclose()`. Pass `grant=Grant.narrow(...)` to bound the handle’s authority.
`async with caracal.delegate(...)`	Create and bind a delegation edge to an existing agent session.
`caracal.headers(allow_root=False, ctx=None)`	Project the bound context (or an explicit `ctx`) into HTTP headers.
`async with caracal.bind(ctx)`	Rebind a captured context into a new async task.
`async with caracal.bind_from_headers(headers, allow_root=False)`	Bind inbound Caracal envelope headers.
`caracal.transport(allow_root=False, ctx=None, scopes=None, **kwargs)`	Return an `httpx.AsyncClient` that injects Caracal headers and Gateway routing. Pass `ctx=` from thread pools or executors; pass `scopes=` to authorize gateway calls with a scoped resource mandate instead of the raw subject token.
`caracal.sync_transport(allow_root=False, ctx=None, scopes=None, **kwargs)`	Synchronous `httpx.Client` counterpart.
`await caracal.fetch(resource_id, path, ctx=None, scopes=None, ...)`	One-call Gateway request to a resource with context and authority injected.
`caracal.context_middleware(verifier=None)`	ASGI middleware factory: propagates context, and enforces at the boundary when a `verifier` is passed.
`caracal.gateway_request(resource_id, path="/")`	Build a Gateway URL and `X-Caracal-Resource` header.
`caracal.mint_mandate(resource_id, scopes, ctx=None, ttl_seconds=None)`	Mint a cached resource mandate carrying the bound agent session and delegation edge; requires client-secret credentials.

Context Propagation

from caracalai import DelegationConstraints

constraints = DelegationConstraints(
    max_hops=1,
    budget=5,
    policy_approved=True,
)

DelegationConstraints uses Python field names: resources, max_depth, max_hops, ttl_seconds, budget, policy_approved, expires_at, and broad_reason.

Protect Inbound Requests

context_middleware() is framework-agnostic and runs on any ASGI app (FastAPI, Starlette, Quart, Django ASGI).

Without a verifier it only propagates: it binds the inbound Caracal envelope into request context but does not check JWT signatures, audience, scopes, token use, or revocation. Use this when a Gateway already enforced the mandate upstream.

Pass verifier= to enforce at the boundary. The callable receives the bearer token and must raise on failure; back it with caracalai_identity.verify_token so the application sees a request only after the mandate is proven. The SDK never inspects token internals itself.

from caracalai_identity import verify_token
from caracalai import Caracal

caracal = Caracal.from_env()
app = FastAPI()

async def verify(token: str) -> None:
    await verify_token(token, issuer=ISSUER, audience=AUDIENCE)

app.add_middleware(caracal.context_middleware(verifier=verify))

See Enforce, propagate, or attribute for which call path verifies authority.