Design tool gateways that constrain delegated agent authority

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

A helpful plan is not an authorization grant

An incident assistant needs to inspect worker health. Its model proposes a tool call that reads worker-7, then suggests restarting the worker when it sees degradation. Both actions may be relevant to the same incident, but they require different authority. The fact that a user asked for help investigating does not imply permission to perform every action the assistant thinks might resolve the problem.

Our proposed gateway accepts only a bounded read_health operation and two known worker targets. It checks identity-related claims and resource scope before calling a provider adapter. The model can request an operation, but application policy decides whether it is allowed. This keeps the authority boundary stable when prompts, model versions or retrieved incident logs change. A polite refusal generated by a model is not the same control as a denied provider call.

Architecture and request sequence

Component diagram for Design tool gateways that constrain delegated agent authority — Original reference architecture by Sandeep Belgavi. Arrows show the responsibilities and transitions described below.

Request sequence for Design tool gateways that constrain delegated agent authority — Illustrative sequence for this design; failure and recovery variants are explained in the article.

Separate authentication from policy evaluation

Authentication establishes who or what presented a request and whether its credentials are valid. Authorization decides whether that established identity may perform the requested operation on the specified resource. The teaching module starts at the second boundary: Claims is a fixture object supplied by trusted code. It does not parse, sign or verify access tokens and must not be exposed directly as a network authentication mechanism.

The policy considers issuer, audience, subject, actor, tenant, scopes and expiry. Subject represents the delegated user in this example; actor identifies the incident agent acting on that user's behalf. Keeping both visible supports an audit question that a shared service account cannot answer alone: which agent used which person's authority for this request? The exact claim format in a real system depends on its identity provider and delegation protocol.

Bind credentials to the intended service

A credential valid for one API should not automatically authorize another. MCP security guidance discusses audience validation and rejects token passthrough as a safe shortcut. Our original gateway uses a fixed expected audience and issuer in fixtures to make that boundary testable. It does not implement MCP or claim compliance with an authorization specification.

The production authentication layer must verify signatures, issuer trust, expiry and protocol requirements using maintained components before constructing trusted claims. The downstream adapter should obtain credentials intended for its own resource rather than forwarding an arbitrary incoming token. Avoid putting a broad token into a model-visible tool argument. If the model can choose which credential to use, it can accidentally cross the very boundary the gateway was meant to enforce.

Authorize the operation and the object

A scope named health:read is necessary in the example, but insufficient by itself. The request's tenant must match the trusted tenant claim, the actor must be the allowed incident agent, and the target must be a known worker identifier. The gateway rejects arbitrary URLs, shell commands and unknown tool names. This reduces the action space before provider execution rather than asking the model to avoid dangerous strings.

A real resource catalog can replace the small allowlist, provided it applies ownership and policy checks to the resolved object. Do not resolve a caller-supplied target to a different resource after authorization without checking again. Redirects, aliases and mutable resource names can otherwise create a gap between the object approved by policy and the object used by the adapter. Prefer stable resource identities and explicit operation schemas.

Capacity and failure assumptions

Assume a read-only incident trial with fifty concurrent investigations, each making four health queries. That creates two hundred potential provider calls before retries. The gateway should impose concurrency and rate limits independently of model token limits. A cheap authorization check does not make the downstream API unlimited, and a provider outage should not encourage the agent to switch to a more privileged tool as a workaround.

The reference runs synchronously in one process with an in-memory audit list. It is designed for policy tests, not traffic handling or durable auditing. A hosted design needs authenticated ingress, a policy service or library, a resource resolver, a credential broker and governed audit storage. Keep denial behavior predictable when dependencies fail. If identity verification or policy data is unavailable, do not reinterpret that outage as permission to continue.

Test the boundary before adding autonomy

The original example allows one synthetic health read and denies a restart request, reporting one provider call and one denial. Its tests cover wrong issuer, wrong audience, expired claims, cross-tenant access, missing scope, wrong actor, arbitrary target and write-tool attempts. Every denial test verifies that the provider call count remains zero.

These assertions show a meaningful local authorization boundary while leaving authentication, revocation and transport security explicitly outside scope. Use evaluation foundations to test whether the assistant selects appropriate tools, but keep those quality checks separate from gateway enforcement. The system should remain safe when the assistant chooses incorrectly. That is the practical reason to place identity and authority in application infrastructure rather than relying on the model's interpretation of a prompt.