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

| 1. Name the action | 2. Guard the execution | 3. Prove the coverage | | --- | --- | --- | | Map document.publish once, rather than inventing a check per surface. | Put the guard immediately before the route handler, Tool callable, MCP callable, retrieval result, or worker side effect. | Compare registered paths, Catalog bindings, and final guards in CI. |

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](docs/quickstart.md), or jump straight to [FastAPI, Tool, MCP, and framework integrations](docs/frameworks.md).

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.

| Keep using | Agent Authz adds | | --- | --- | | Casbin, OPA, Cerbos, OpenFGA, SpiceDB | A common execution contract and a final guard at Python application boundaries. | | FastAPI, MCP, agent frameworks | A way to map their heterogeneous entrypoints to one operation vocabulary. | | Your database and identity provider | Trusted resource loading: tenant, ownership, and relations come from host-owned data, never model output. | | Your CI and audit stack | Coverage evidence, decision metadata, and privacy-safe audit primitives. |

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:

~~~python from authzsdk import AgentRuntime, protecttool

runtime = AgentRuntime(authz)

@protecttool( runtime=runtime, operation="document.read", subject=lambda call: call.kwargs["subject"], resourcetype="document", resourceid=lambda call: call.kwargs["documentid"], ) def readdocument(*, subject, documentid): 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?

| Capability | What it catches | | --- | --- | | CoverageManifest | Missing final guards, missing declared data boundaries, and unmapped Catalog operations. | | FastAPI route inventory | Live registered routes, mounted sub-applications, and matching Authz guards in FastAPI's assembled dependency graph. | | CandidateFilter | Retrieval candidates that must not enter an LLM prompt. | | ExecutionPermit + RedisPermitStore | Replay of high-risk approvals across workers; shared-store outages fail closed. |

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](docs/coverage.md) for the exact contract.

Fits around your stack

| Surface | Availability | Execution boundary | | --- | --- | --- | | Native core + Authz.production() | Available | Catalog, trusted resources, policy, final decision | | FastAPI | Available extra | Dependency guard before the handler | | Python Agent Tools | Available | Sync/async callable guard before execution | | MCP Python SDK 2.x | Beta extra | Registered MCP Tool callable; host owns MCP authentication | | Agno / LangGraph | Foundation wrappers | Tool and node execution guards | | Casbin | Available extra | Existing enforcer behind the common request/decision contract | | OPA / Cerbos / OpenFGA / SpiceDB | Experimental transports | Fail-closed starter adapters, not complete vendor clients | | RAG | Available primitive | Filter candidates before prompt assembly |

See the [integration matrix](docs/frameworks.md), [policy backend boundaries](docs/backends.md), and [deployment patterns](docs/deployment.md).

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](docs/production.md), [deployment patterns](docs/deployment.md), and [threat model](docs/threat-model.md).

Learn, evaluate, contribute

| Start with | Then evaluate | Before production | | --- | --- | --- | | [Quickstart](docs/quickstart.md) | [Architecture](docs/architecture.md) · [Comparison](docs/comparison.md) | [Production](docs/production.md) · [Security](SECURITY.md) | | [Agent runtime](docs/agent-runtime.md) | [MCP](docs/mcp.md) · [Coverage](docs/coverage.md) | [Supply chain](SUPPLY_CHAIN.md) · [Deployment](docs/deployment.md) |

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

License

Apache-2.0. See [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: FrankPlusPlus
• Source: FrankPlusPlus/agent-authz
• License: Apache-2.0
• Homepage: https://github.com/FrankPlusPlus/agent-authz

Install and usage instructions live in the source repository linked above.