For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Fault injection
Inject artificial latency into requests to test how your clients and services handle slow responses.
Attaches to:
llm or mcp modes, the examples on this page show each option in tabs. For more information, see Routing-based configuration.Fault injection adds artificial latency to matching requests before agentgateway forwards them to the backend. Use it to test how your clients and upstream services behave when responses are slow, such as verifying that timeouts, retries, and client-side deadlines work as expected.
The injected delay counts against the request timeout. If the delay is longer than the configured request timeout, the request times out.
Inject a delay
Set delay.duration in the route policies. The duration can be either of the following values.
| Value | Description |
|---|---|
| A duration string | A fixed latency to inject, such as 2s or 500ms. |
| A CEL expression | An expression that is evaluated against each request and returns a duration or a number of milliseconds. Use this option for conditional, probabilistic, or randomized delays. A non-positive result injects no delay. |
The following example injects a fixed 2-second delay before agentgateway forwards requests to the backend.
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
port: 3000
policies:
delay:
duration: 2s
targets:
- name: everything
stdio:
cmd: npx
args: ["@modelcontextprotocol/server-everything"]Inject a probabilistic or random delay
Because duration accepts a CEL expression, you can inject latency into only a subset of requests, or add jitter. The expression returns either a duration or a number that is interpreted as milliseconds.
| Expression | Effect |
|---|---|
duration("500ms") | A fixed 500ms delay, expressed as a CEL duration. |
random() < 0.1 ? 500 : 0 | A 500ms delay on approximately 10% of requests, and no delay otherwise. |
int(random() * 500.0) | A random delay between 0 and 500ms (jitter) on every request. |
The following example delays approximately 10% of requests by 500ms.
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 3000
listeners:
- routes:
- policies:
delay:
duration: "random() < 0.1 ? 500 : 0"
backends:
- host: localhost:8080