Docs / Config object
// CONFIGURE THE GATEWAY
The GatewayConfig object
One declarative object controls routing, fallback, caching, retries, and inline guardrails for a tenant or a single request. Attach it to a key, or pass it per-call with the x-agentics-config header. Every decision it drives is recorded on a child receipt, so the path a request took is itself provable.
Top-level fields
| Field | Type | Meaning |
|---|---|---|
| strategy | enum | single | fallback | loadbalance | conditional. How targets are chosen. |
| targets | Target[] | Ordered list of upstreams. Each is { provider, model, weight?, on?, config? }. |
| cache | object | { mode: "off"|"simple"|"semantic", ttl_s, threshold? }. A cache hit still writes a proof-only receipt. |
| retry | object | { attempts, backoff_ms, on:[status…] }. Retries are receipted as routing children, never re-billed. |
| guardrails | object | { input:[Check…], output:[Check…] }. Each check that runs emits a guardrail receipt. |
| budget | object | { limit_usd, window, on_exceed: "block"|"warn" }. Hard-stops fire before dispatch. |
| params | object | Param shaping: defaults to apply and keys to drop before the provider call. |
Routing strategies
- single — always the first target. The simplest config.
- fallback — try targets in order; advance on the statuses in each target's
on. - loadbalance — split traffic across targets by
weight. - conditional — pick a target by evaluating the routing DSL against request context.
The routing condition DSL
A condition is a small JSON expression evaluated against request context — headers, metadata, token estimates, and message fields. Operators compose:
| Operator | Form | Meaning |
|---|---|---|
| eq, ne | { "eq": ["$meta.tier", "pro"] } | Equality / inequality on a context path. |
| gt, lt, gte, lte | { "gt": ["$tokens_in", 4000] } | Numeric comparison. |
| in | { "in": ["$meta.region", ["eu","uk"]] } | Membership. |
| and, or, not | { "and": [ … ] } | Boolean composition; nests arbitrarily. |
| matches | { "matches": ["$user", "@acme\\.com$"] } | Regular-expression test. |
Context paths start with $: $tokens_in, $user, $meta.<key>, $model.
Worked example: nested conditional
Route long EU-region requests to a regional upstream, fall back otherwise, and cache semantically — with an inline output guardrail and a budget hard-stop. Every branch this config takes lands on a receipt.
{
"strategy": "conditional",
"targets": [
{
"provider": "@anthropic", "model": "claude-opus-4-8",
"on": {
"and": [
{ "in": ["$meta.region", ["eu", "uk"]] },
{ "gt": ["$tokens_in", 4000] }
]
}
},
{ "provider": "@anthropic", "model": "claude-haiku-4" } // default fallback
],
"cache": { "mode": "semantic", "ttl_s": 3600, "threshold": 0.92 },
"retry": { "attempts": 2, "backoff_ms": 250, "on": [429, 502] },
"guardrails": { "output": [{ "check": "pii_egress", "action": "block" }] },
"budget": { "limit_usd": 500, "window": "day", "on_exceed": "block" }
}child_of=parent, billable=false receipt. The path a request took through this config is reconstructable from the ledger — you don't take the gateway's word for which branch fired.