agent-authz

Agent Authz

Authorization integrity at the moment an Agent action executes.
One business operation · every registered path · one final decision before work happens.

Agent Authz is an embedded Python Policy Enforcement Point (PEP) for the moment an agent action actually runs. It maps a registered API route, Agent Tool, MCP Tool, retrieval boundary, or worker to a business operation; loads trusted tenant and resource facts; then allows or denies before protected data is returned or a side effect begins.

It works beside the policy system you already use. Your application continues to own identity, business data, transactions, and policy distribution.

The execution-integrity loop

API route ─┐
Agent Tool ├──> document.publish ──> trusted facts ──> allow / deny ──> side effect
MCP Tool  ─┤
worker    ─┤
retrieval ─┘

Start here

Clone the public Beta and run the dependency-free end-to-end example:

git clone https://github.com/FrankPlusPlus/agent-authz.git
cd agent-authz
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
python examples/secure_document_agent.py

It exercises the real model of the SDK—not a toy allow-list:

api_allowed=True          tool_allowed=True
tool_denied=True          cross_tenant_denied=True
permitted_chunk_ids=['chunk-public']
permit_status='consumed'  coverage_ready=True

Then follow the five-minute quickstart, or jump straight to FastAPI, Tool, MCP, and framework integrations.

Why Agent Authz

An agent can reach the same business action through far more than an HTTP endpoint. A route guard alone does not protect a Tool called directly; a policy engine alone cannot show whether every executable path applied that policy.

That is the product boundary: Agent Authz is not a PDP, IAM system, relationship database, vector database, agent framework, gateway, or hosted control plane. It is the thin runtime layer that keeps authorization from drifting at the execution boundary.

A minimal production-shaped guard

Define the resource and policy once. The loader is owned by the host service, so the model cannot assert tenant or relationship facts for itself.

from authz_sdk import Authz, Catalog, PolicySet, ResourceRegistry, Subject

catalog = Catalog()
catalog.resource("document", actions=("read",), relations=("viewer",), tenant_required=True)

policies = PolicySet()
policies.bind(
    id="document_viewers_read",
    operation="document.read",
    template="relation",
    relations=("viewer",),
)

documents = {
    "doc-1": {"tenant_id": "acme", "viewers": {"alice"}, "body": "Private launch plan"}
}
resources = ResourceRegistry()

def load_document(document_id, subject, context):
    row = documents.get(document_id)
    if row is None or row["tenant_id"] != subject.tenant_id:
        return None
    return {
        "id": document_id,
        "attributes": {"tenant_id": row["tenant_id"]},
        "relations": {"viewer": subject.id in row["viewers"]},
    }

resources.register("document", load_document)
authz = Authz.production(catalog, policies, resources)

decision = authz.can(
    Subject(id="alice", tenant_id="acme"),
    operation="document.read",
    resource_type="document",
    resource_id="doc-1",
)
assert decision.allowed

Put the same operation immediately around the callable that returns data or causes the effect:

from authz_sdk import AgentRuntime, protect_tool

runtime = AgentRuntime(authz)

@protect_tool(
    runtime=runtime,
    operation="document.read",
    subject=lambda call: call.kwargs["subject"],
    resource_type="document",
    resource_id=lambda call: call.kwargs["document_id"],
)
def read_document(*, subject, document_id):
    return documents[document_id]["body"]

Proof, not promises

Most authorization libraries can answer a policy question. Agent Authz also helps answer an operational question: did the application attach the final check everywhere it claims to?

Coverage evidence is intentionally scoped: FastAPI has strict evidence from its assembled dependency graph; generic Python Agent tools, MCP, and task registries are explicit host attestations unless their framework exposes an inspectable registry. The report labels these levels rather than pretending to scan arbitrary Python code or protect an unintegrated service. Read Coverage evidence for the exact contract.

Fits around your stack

See the integration matrix, policy backend boundaries, and deployment patterns.

Production boundary

Agent Authz can fail closed for its own decision and permit store. The host application is still responsible for:

• authenticating the caller and supplying a verified, request-local Subject;
• loading tenant, ownership, and relationship facts from a trusted source;
• placing the final guard immediately before a side effect;
• routing each relevant execution path through a registered guard;
• durable audit storage, query pushdown, key management, and outage policy.

For the exact threat model and multi-worker/microservice guidance, read the production guide, deployment patterns, and threat model.

Learn, evaluate, contribute

The public roadmap is in ROADMAP.md. Please read CONTRIBUTING.md before opening a pull request.

License

Apache-2.0. See LICENSE.