Route every tool the agent can call through one gateway that holds the downstream credentials, exposes one route per capability, validates each request against a strict schema, and asks the policy layer for a verdict before forwarding anything that changes state. The agent holds a single scoped token. Every call is logged with a correlation identifier.
What does the gateway do, and who owns it?
An agent uses tools by sending structured requests: look up an account, create a ticket, issue a refund. The explainer on how an AI agent uses tools covers the mechanics. Without a gateway, each tool connects directly to its system with its own credentials, and the agent, or the code around it, ends up holding a pocketful of secrets.
A gateway puts one controlled door in front of all of them. It handles authentication, routing, request validation, quotas and logging. It does not on its own decide whether this agent, on this case, may take this action at this amount; that is the job of the policy layer the gateway calls. Keep the two separate: the gateway is plumbing that cannot be bypassed, the policy layer is judgement that is enforced.
The platform or integration team owns the gateway. Each system owner owns the routes into their system and approves what each route may do.
How do you put it in place, step by step?
- Integration team: inventory the agent's tools. For each, the system it reaches, the operation, and whether it reads, drafts, executes or moves money.
- System owners: approve one route per capability. "Read invoice status" and "mark invoice disputed" are separate routes, even if the system exposes them as one endpoint with a flag. Evidence: a route list with an owner per route.
- Integration team: move downstream credentials into the gateway. The agent receives one token, scoped to its routes. Rotating a downstream secret no longer touches the agent. Evidence: no system secrets in agent configuration.
- Integration team: define a strict schema per route. Typed fields, ranges, allowed values. Reject anything else, including extra fields. Evidence: rejected requests with the schema error.
- Integration team: filter responses. Strip fields the capability does not need before they reach the agent.
- Platform: call the policy layer on every state-changing route. The gateway forwards only on allowed. On held, it returns a reference the agent can report; on refused or withheld, a reason. Evidence: verdict reference on each call.
- Integration team: require idempotency keys on writes. An agent that retries after a timeout must not pay twice.
- Integration team: keep admin and bulk routes off the agent's gateway entirely. If a route does not exist, it cannot be misused.
| Step | The agent does | Depth | Stays with a person |
|---|---|---|---|
| Inventory | Nothing | none | Integration team lists tools |
| Approve routes | Nothing | none | System owners approve each route |
| Read routes | Calls lookups | 1 | Nothing |
| Draft routes | Creates drafts in the target system | 2 | A person sends or commits |
| Routine write routes | Executes within bounds | 3 | Person sets the bounds |
| Money routes | Proposes payments or refunds | 4, or held | Approver above limits |
| Admin routes | Not exposed | none | System administrators only |
Which controls matter, and what evidence do they leave?
Credentials stay behind the gateway. Evidence: secrets inventory showing none held by agents.
Narrow routes. Generic routes such as "call any endpoint" defeat the purpose. Good routes look like good tools; see how to design tools for AI agents. Evidence: route list reviewed at each certification.
Schema validation. Free-text fields are where injected instructions and malformed amounts slip through. Evidence: rejection log.
Policy verdict before forwarding. Evidence: each forwarded write carries an allowed verdict reference; each held write carries an approver.
Rate limits. Volume is a bound in its own right; the method is in how to rate-limit an AI agent at the API gateway. Evidence: throttled calls in the log.
Correlated logging. One identifier ties the agent's decision, the verdict, the gateway call and the downstream response. Evidence: a trace per action.
What should you measure?
- Schema rejections per route. A rise often means the agent's brief or the tool description has changed.
- Verdict mix per route: allowed, held, refused, withheld.
- Retries and duplicate idempotency keys. Many retries suggest timeouts downstream.
- Fields stripped from responses. If a capability keeps asking for stripped fields, revisit the route or the brief.
- Calls not through the gateway. Should be zero; check downstream logs for the agent's old credentials.
Where does it usually go wrong?
The gateway is treated as the governance layer. It can authenticate and throttle; it cannot tell whether a refund is justified by the facts of the case. Pair it with a policy check.
One route per system, not per capability. A single "ledger" route with full rights makes every bound depend on what the agent chooses to send.
Old credentials survive. The agent's original keys still work, so a misconfigured tool can bypass the gateway. Revoke them on the day of cut-over.
Responses leak. The gateway validates requests carefully and passes back full records, including fields the agent should never see.
Payments get no special treatment. Payment routes need idempotency, amount bounds and held verdicts above limits; connecting an agent to your payment gateway covers that system in detail.
Where Pryme fits
In Pryme, every tool call is an action evaluated against the minimum chain of bounds before it reaches a system, so the gateway forwards only what has a verdict. Sources returned by tools arrive stamped with their provenance. The governed agentic operating system guide explains how the gateway, bounds and record fit together.
Questions people ask
Can we use our existing API gateway?
Usually, yes. The work is in defining narrow routes per capability, moving secrets behind it, and adding the policy call for state-changing routes. The product matters less than the configuration.
Should read-only routes go through the policy check too?
Yes, though they are cheaper to evaluate. Reads can expose personal data or be used to probe, and the record should show what the agent looked at.
What happens if the gateway is down?
The agent cannot act. That is the right failure: a tool that works when the gateway is down is a tool with a bypass.