> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pecta.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Latency gate: enforce response time limits

> Fail any agent output whose upstream latency exceeds a configurable millisecond threshold, with automatic skip when no latency is recorded.

The latency gate compares `ctx.latency_ms` against a threshold you set and fails the evaluation if the value is too high. Use it when your application has strict response-time contracts — for example, an RTB bidder that must respond in under 100 ms, or a customer-facing chat assistant where slow responses degrade user experience.

If `ctx.latency_ms` is not provided in the evaluation context, the gate returns `skipped: true` and is treated as passing. This lets you enable the gate globally and skip it on evaluations where upstream timing is not yet instrumented.

## Usage

```typescript theme={null}
import { createEngine, gates } from "@pecta/core";

const engine = createEngine({
  gates: [
    gates.latency({ maxMs: 100 }),
  ],
});

const result = await engine.evaluate({
  agent_id: "my-agent",
  output: { text: "Hello, world!" },
  latency_ms: 143,
});
```

## What a failure looks like

When the gate fails, its entry in `result.gates` looks like this:

```json theme={null}
{
  "name": "latency",
  "passed": false,
  "reason": "latency 143ms exceeds 100ms threshold",
  "latency_ms": 0.08
}
```

`latency_ms` in the gate result is the time the gate itself took to run (always sub-millisecond), not the upstream response time.

## What a skip looks like

When `latency_ms` is absent from the evaluation context:

```json theme={null}
{
  "name": "latency",
  "passed": true,
  "skipped": true,
  "reason": "no latency_ms provided",
  "latency_ms": 0.04
}
```

## Configuration

<ParamField path="maxMs" type="number" required>
  The maximum allowed latency in milliseconds. Must be a positive finite number. The gate throws at construction time if you pass `0`, a negative value, `Infinity`, or `NaN`.
</ParamField>

<ParamField path="name" type="string">
  Override the gate name recorded in results. Defaults to `"latency"`. Useful when you register multiple latency gates with different thresholds and need to tell them apart in `result.gates`.
</ParamField>

## Multiple thresholds

You can register more than one latency gate with different names and thresholds to create warning and hard-fail bands:

```typescript theme={null}
import { createEngine, gates } from "@pecta/core";

const engine = createEngine({
  gates: [
    gates.latency({ maxMs: 150, name: "latency.warn" }),
    gates.latency({ maxMs: 300, name: "latency.hard" }),
  ],
  failFast: false, // collect both verdicts
});
```

<Note>
  Gate names must be unique within an engine. If you add two gates with the same name, `createEngine` throws immediately.
</Note>