Request context

Real backends serve many users, and different users get different capabilities. Hexgate splits that into two pieces:

HexgateContext — the per-request scope. Marks “this invocation acts on behalf of alice, with roles X, and these attributes.” Async context manager; pushes a fact-bearing Biscuit through the agent runtime.
Role policies — one policy.yaml per role, optionally inheriting from a base mixin. The runtime picks the right one at call time based on the active context’s primary role.

The two are deliberately decoupled: tokens carry identity (who is calling), policy files carry rules (what they can do).

Minimal example

from hexgate import HexgateContext, load_hexgate_agent, stream_agent

agent, handler = load_hexgate_agent("support_bot")          # client + roles attached at load

async with HexgateContext(user_id="alice", user_roles=["billing"], ttl_seconds=300):
    async for event in stream_agent(agent, handler, "refund customer 30"):
        ...

No manual attenuate_for_user, extract_facts, or ToolUseContext plumbing at the call site. The runtime mints the per-request token, picks the billing role’s policy file, and evaluates its constraints against each tool call.

Filtering on attributes (`ctx.*`)

Beyond the role, a context can carry an open attributes bag that policy constraints read through the ctx.* namespace — turning role-based access into attribute-based (ABAC) filtering:

async with HexgateContext(
    user_id="alice",
    user_roles=["billing"],
    attributes={"department": "finance", "region": "EU", "clearance_level": 3},
):
    async for event in stream_agent(agent, handler, "refund customer 30"):
        ...

# the billing policy can now gate on caller attributes, not just role
tools:
  refund_order:
    mode: allow
    constraints:
      - args.amount <= 500
      - 'ctx.department == "finance"'
      - "ctx.clearance_level >= 3"

A missing ctx.<key> fails closed (deny), like any absent reference.

Attributes are exactly as trustworthy as the code that sets them. ctx.* may gate deny decisions, but it carries the same trust contract as user_roles: populate attributes from trusted server-side data (your auth/session/IdP), never from raw client input. Hexgate does not independently verify attribute values.

FastAPI pattern

The scope must enclose the streaming iteration itself, because the role is resolved lazily — read on each tool call as the agent runs (see Notes). The robust shape is to open the scope inside the generator that produces the response:

from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from hexgate import HexgateContext, load_hexgate_agent, stream_agent

app = FastAPI()
agent, handler = load_hexgate_agent("support_bot")          # at startup

@app.post("/chat")
async def chat(request: Request, req: ChatRequest):
    auth = await authenticate(request)                       # your auth

    async def scoped_events():
        # scope wraps the iteration, so every tool call sees the role
        async with HexgateContext(
            user_id=auth.id,
            user_roles=auth.roles,                            # e.g. ["billing"]
            session_id=request.state.session_id,
            attributes={"department": auth.department},       # trusted server data
            ttl_seconds=300,
        ):
            async for event in stream_agent(agent, handler, req.message):
                yield event

    return StreamingResponse(scoped_events())

Don’t scope auth in @app.middleware("http"). Starlette’s BaseHTTPMiddleware returns the response before the StreamingResponse body is iterated, so a async with HexgateContext(...): return await call_next(request) exits the scope before the first event is produced. Because hexgate resolves the role at tool-call time, every call during streaming then reads no role and silently falls back to the default policy — a silent authorization downgrade, no error raised. Scope inside the generator (above), or use a pure ASGI middleware that wraps the send channel — not BaseHTTPMiddleware.

For a non-streaming endpoint, async with HexgateContext(...): return await invoke_agent(...) is fine — the agent runs to completion inside the scope.

`HexgateContext` fields

Field	Type	Required	Effect
`user_id`	`str`	✅	Becomes `user("alice")` in the attenuated Biscuit.
`user_roles`	`list[str]`	optional	The first role selects which role policy file applies at tool-call time. Fall-back: the `default` role.
`session_id`	`str?`	optional	Trace tagging — surfaces on Langfuse spans.
`attributes`	`dict[str, str \| int \| bool \| list[str]]`	optional	Caller attributes exposed to `ctx.*` constraints. Populate from trusted server data.
`ttl_seconds`	`int?`	optional	Embeds a `check if time($t), $t < now+ttl` predicate so the token can’t outlive the request.

Only the first role in user_roles reaches policy selection today (read via primary_role); the rest are carried but inert until multi-role selection lands.

Role policies — one file per role

Agents that need per-role behaviour ship a policies/ directory instead of a single policy.yaml:

agent/
├── agent.yaml
├── system.md
└── policies/
    ├── default.yaml          # fallback when no role matches
    ├── read_only.yaml        # mixin — is_mixin: true
    ├── support.yaml          # inherits: [read_only]
    └── billing.yaml          # inherits: [read_only, support]

Each role file is a complete AgentPolicy. Inheritance is left-to-right, child wins on conflicts:

# policies/read_only.yaml  (mixin — safe base)
version: 1
is_mixin: true
default_policy:
  mode: deny
tools:
  view_orders:  { mode: allow }
  list_tickets: { mode: allow }

# policies/billing.yaml
version: 1
inherits: [read_only]
tools:
  refund_order:
    mode: allow
    constraints:
      - args.amount <= 500
      - args.currency == "USD"
  wire_transfer:
    mode: approval_required
    constraints:
      - args.amount <= 100000

See constraints for the expression grammar (including ctx.*) and a role-scoped end-to-end walkthrough.

Notes

Single-file policies still work. A legacy policy.yaml is treated as the default role — no migration needed.
Lazy attenuation. HexgateContext.__aenter__ only pushes a contextvar — the cryptographic work happens inside stream_agent / invoke_agent the first time the agent runs. Errors surface at first agent call, not at scope entry.
Local agents skip attenuation. A context scope around a load_local_agent agent logs a warning and runs with no facts. The default policy still applies — use load_hexgate_agent for the full signed chain.
Explicit override. Passing tool_use_context= explicitly to stream_agent / invoke_agent wins over an active context scope. Useful for tests or one-off bypass.
Sync callers. HexgateContext exposes both async with ctx: and ctx.sync_scope(). The async form is the primary API; the sync mirror exists for CLI loops and Runner.run_sync-style callers.

Get started

Concepts

Framework adapters

Policy

CLI

Request context

Minimal example

Filtering on attributes (`ctx.*`)

FastAPI pattern

`HexgateContext` fields

Role policies — one file per role

Notes

​Minimal example

​Filtering on attributes (ctx.*)

​FastAPI pattern

​HexgateContext fields

​Role policies — one file per role

​Notes

Minimal example

Filtering on attributes (`ctx.*`)

FastAPI pattern

`HexgateContext` fields

Role policies — one file per role

Notes