Build a delegated tool policy with a narrow provider adapter

Pattern 10 companion: Python example · Behavioral tests · Example license

Run the policy demonstration

Download pattern_10.py and its tests. Use Python 3.11 or newer with py -3 -B pattern_10.py on Windows or python3 -B pattern_10.py on macOS. Windows execution was checked; the macOS command is provided for an independent portability run. No additional packages, network credentials or model access are required.

The script returns status degraded, provider_calls one and denied one. It first requests a permitted health read, then attempts a restart through the same gateway. The second request fails before the adapter runs. This is a policy laboratory, not a token server or an MCP implementation. The synthetic claims are intentionally visible so readers can change one field and observe the resulting denial.

Architecture and request sequence

Component diagram for Build a delegated tool policy with a narrow provider adapter — Original reference architecture by Sandeep Belgavi. Arrows show the responsibilities and transitions described below.

Request sequence for Build a delegated tool policy with a narrow provider adapter — Illustrative sequence for this design; failure and recovery variants are explained in the article.

Read the claims object carefully

Claims is a frozen dataclass with issuer, audience, subject, actor, tenant, scopes and expires. Frozen prevents ordinary attribute reassignment in this local program; it is not cryptographic integrity. Anyone who controls the calling Python code can construct another Claims object. A deployed boundary must only build this object after a trusted authentication component verifies the actual credential and its protocol constraints.

The fixture represents operator-3 delegating a health read to incident-agent in team-a, with an expiry at logical time two hundred. It uses a frozenset for scopes. These values are synthetic and carry no real authority. The example keeps them explicit because hiding identity behind a generic authorized boolean would make it impossible to test audience, actor and tenant failures independently.

Follow the policy checks in order

Gateway.call checks the expected issuer and audience, requires a subject and the selected actor, rejects expired claims, compares the requested tenant, validates the tool and scope, then checks the target allowlist. The first failure becomes a reason code. Before returning or raising, the method appends a structured audit item containing actor, subject, tool, decision and reason.

The policy uses exact comparisons and a small fixed allowlist. This makes its behavior easy to inspect but limits it to the teaching scenario. A production resource policy may depend on incident ownership, environment, time or approved action context. Add those attributes explicitly and test each one. Do not replace the checks with a model's judgment that the request looks reasonable; the gateway exists to constrain an incorrect or manipulated request.

Keep the adapter narrow

HealthAdapter exposes read_health with tenant and target parameters, increments a call counter and returns a deterministic degraded status with a synthetic source marker. It has no general HTTP method, arbitrary URL input, shell execution or credential argument. The narrow interface is useful because authorization can reason about a specific operation rather than trying to interpret a generic command string.

When implementing a real provider adapter, derive the endpoint and credential from trusted configuration. Resolve the target to an authorized resource, use bounded timeouts and validate the response schema. If the provider uses redirects or aliases, ensure they cannot move the request to an unintended destination. The adapter seam does not remove the need for transport security or provider-side access control; it gives those concerns a defined place to be implemented.

Use denial tests as executable policy

Run py -3 -B -m unittest test_pattern_10, or the equivalent python3 command. Ten tests exercise audience, issuer, tenant, expiry, scope, write operation, actor and arbitrary-URL rejection, plus allowed audit behavior and the demonstration result. The helper for denied requests checks both the exception and the zero provider-call count. That second assertion proves the local side-effect boundary was respected.

The expiry test uses equality with the expiry timestamp, ensuring the credential is invalid at that boundary. The arbitrary-URL test demonstrates that target is a resource identifier rather than an open network destination. These are concrete policy properties. They do not prove token signature verification, revocation, replay resistance or protection against every request-shaping attack, because those mechanisms are not implemented in this offline module.

Build the missing deployment layers explicitly

A hosted reference would place maintained authentication middleware before Gateway.call, derive trusted claims from validated credentials and record audit outcomes in durable storage. It would also apply request size limits, structured error handling, rate limits and a policy version. MCP's security guidance is a useful source for protocol-specific risks, but copying this fixture does not establish compliance or complete an OAuth flow.

Keep authentication failures separate from authorization denials in internal telemetry while avoiding sensitive detail in public errors. Test that invalid credentials never reach the policy function and that denied policy requests never reach the provider. Finally, evaluate the incident assistant's reasoning separately: an authorized health read can return data that the model misunderstands. The gateway limits authority; it does not certify the quality of the diagnosis produced afterward.