Surface routing model
The Surface routing model explains how one Agent Surface handles inbound and outbound traffic for one managed agent. It defines the responsibilities of Access Point, Target, Transit Point, and Listener, and clarifies why these are separate concepts.
| Concept | Direction | Role |
|---|---|---|
| Access Point | Inbound | Entry point for callers; owns authentication, rate limiting, and caller context. |
| Target | Inbound | The managed agent endpoint the gateway forwards inbound calls to. |
| Transit Point | Outbound | Route for the managed agent to call external services under gateway control. |
| Listener | Both | Gateway-level network binding (address and port). Access Points and Transit Points register route paths on a Listener. They do not own it. |
Access Point
The Access Point is the inbound face of a surface. It defines the network address, route path, and protocol that external callers use to reach the managed agent through the gateway. It is the front door for one surface.
An Access Point owns inbound caller controls:
- Caller authentication (multiple source-auth methods can be configured and evaluated in order).
- Inbound rate limiting.
- Caller context mode (required identity, optional identity, or anonymous requests).
Target (External Target)
The Target (or External Target) is the destination side of a surface. After inbound requests pass gateway-level and surface-level controls, the gateway forwards traffic to the Target endpoint.
Each surface has exactly one Target.
In the surface model, the managed agent represents the external endpoint within the surface configuration. The external endpoint itself remains outside gateway control, while policy and routing behaviour stay inside the surface representation.
Transit Point
A Transit Point is a named, gateway-managed egress route that your managed agent uses to make outbound calls. It registers one outbound channel on the gateway’s outbound listener and exposes a URL that the managed agent calls instead of the external destination directly.
Where Access Point and Target model the inbound flow (caller → managed agent), Transit Point models the reverse (managed agent → external endpoint). Without a Transit Point, outbound calls from the managed agent bypass the gateway entirely: they carry no policy gate, no authentication controls, and no visibility into what the agent called, regardless of what is configured on the inbound surface.
A surface can have zero or more Transit Points.
Each Transit Point has two identifiers:
- Display name: shown in the dashboard for labelling only. Free text field.
- Alias: a URL-safe routing identifier (for example,
github-apiorpartner-service) that forms the path segment of the Transit Point URL. The alias also appears as a claim in the transit token so the gateway knows which Transit Point to route the call through.
Each Transit Point is an independent processing pipeline. You can attach Policy, Rate Limit, Networking, Payment, and Trust Registry controls to an individual Transit Point without affecting other outbound routes on the same surface.
A Transit Point can target two destination types:
- External URL: a standard HTTPS or agent endpoint the gateway calls on behalf of the managed agent.
- Gateway-to-gateway: a Gateway Connection target (
fabric://) that routes the call through another Trust Gateway instance.
Inbound and outbound flows
The inbound and outbound flows do not chain together. They are two separate pipelines on two separate listeners.
The managed agent is an external service you run. It receives calls from the gateway on the inbound side, and it initiates calls through the Transit Point on the outbound side.
The Transit Point is on a separate listener port from the Access Point. Setting the managed agent target endpoint to a Transit Point URL does not chain the flows. It sends inbound traffic to the wrong listener and returns a 404.
The transit token
The gateway binds the two flows together through a short-lived JWT called the transit token. It is generated during the inbound pipeline, before the gateway forwards to the managed agent, and injected as the X-Transit-Token request header.
When the managed agent calls the Transit Point URL, it includes this same token as X-Transit-Token. The gateway validates the token on the outbound side before forwarding.
| Claim | Carries |
|---|---|
| Surface identity | The surface ID the token was issued for. |
| Caller identity | The caller’s DID and identity source, if resolved. |
| Expiry | 5 minutes from issue. The managed agent must make the outbound call within the same request lifecycle. |
| Routing scope | The Transit Point aliases the token is valid for. |
| Caller context | Fields from Caller Context elements on the surface, used for Workload Binding. |
| Identity reference | A user identity reference for Credential Delegation lookups. |
| Supporting fields | Replay protection, end-to-end trace correlation, and issuing gateway attribution. |
The token is opaque to the managed agent. It does not decode or generate it. It reads the header from the inbound request and attaches it unchanged to the outbound call.
When to use Transit Points
Use a Transit Point when your managed agent needs to call an external service and you want the gateway to govern that outbound call. The gateway can:
- Apply policy checks to outbound calls before they leave the gateway.
- Apply policy checks to responses before they reach your agent.
- Verify the external destination against a trust registry.
- Inject API keys or tokens into outbound requests without passing them through the managed agent.
- Rate-limit outbound traffic per destination, independently of inbound calls.
- Record outbound calls in metrics and traces alongside inbound activity.
You can add multiple Transit Points to a single surface, one per outbound destination. Each runs as a separate pipeline so different destinations can carry different policies, credentials, and rate limits.
If your managed agent processes requests entirely on its own, or calls external services directly without needing gateway governance, Transit Points are not required.
For a step-by-step walkthrough, see Apply policy to outbound calls.
Listener
A Listener is a gateway-level network binding: a specific address and port the gateway opens at startup to accept connections. Listeners are configured once on the gateway, not per surface. Multiple surfaces can share the same Listener.
Access Points and Transit Points do not own a Listener. They register a route path on one. When a request arrives on a Listener address, the gateway matches the request path to the correct Access Point or Transit Point across all surfaces.
| Concept | Scope | Role |
|---|---|---|
| Listener | Gateway-wide | A bound address and port, opened once at startup and shared across surfaces. |
| Access Point | Per surface | Registers an inbound route path on a Listener. Owns authentication and rate limiting for that route. |
| Transit Point | Per surface | Registers an outbound route path on a Listener. Owns controls for that egress destination. |
Listener bindings are startup-only configuration. Changing a Listener address or port requires a process restart, not a hot reload.
Routing model recap
For each managed agent surface:
- Inbound flow: caller → Access Point → Target.
- Outbound flow: managed agent → Transit Point → external endpoint.
Understanding these relationships is the foundation for surface design, policy enforcement, and runtime governance in Agent Gateway.
Related
- Surfaces: High-level overview of Agent Surface structure and runtime behaviour.
- Apply policy to outbound calls: Add Transit Points to a surface and apply OPA policy and trust checks to your managed agent’s outbound calls.
- OPA policies: Policy enforcement used across inbound and outbound paths.
- Gateways: Multi-hop routing and Gateway Connection across gateway boundaries.
Glad to hear it! Please tell us how we can improve more.
Sorry to hear that. Please tell us how we can improve.
Thank you for sharing your feedback so we can improve your experience.