Skip to main content

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.

The schema gate runs a Zod safeParse against ctx.output (or ctx.input when you set target: "input") and fails the evaluation if validation does not succeed. It is the right tool when your agent is expected to return structured data — a JSON object, a typed array, a specific string format — and you need a hard guarantee that every field is present and correctly typed before the output reaches downstream code. On failure, the gate returns up to five Zod validation issues in details so you can diagnose exactly which fields are wrong without needing to re-run the agent.

​
Usage

import { createEngine, gates } from "@pecta/core";
import { z } from "zod";

const BidResponseSchema = z.object({
  id: z.string(),
  seatbid: z.array(
    z.object({
      bid: z.array(
        z.object({
          id: z.string(),
          impid: z.string(),
          price: z.number().positive(),
          adm: z.string().optional(),
        })
      ),
    })
  ),
});

const engine = createEngine({
  gates: [
    gates.schema(BidResponseSchema),
  ],
});

const result = await engine.evaluate({
  agent_id: "dsp-bidder",
  output: {
    id: "abc123",
    seatbid: [{ bid: [{ id: "b1", impid: "imp1", price: -0.5 }] }],
  },
});

​
What a failure looks like

When validation fails, reason contains a human-readable summary and details contains the raw Zod issues (capped at five): 
{
  "name": "schema",
  "passed": false,
  "reason": "schema validation failed (1 issue): seatbid.0.bid.0.price: Number must be greater than 0",
  "latency_ms": 0.31,
  "details": {
    "issues": [
      {
        "path": ["seatbid", 0, "bid", 0, "price"],
        "code": "too_small",
        "message": "Number must be greater than 0"
      }
    ],
    "total": 1
  }
}
details.total reflects the true number of Zod issues even when more than five exist.

​
Configuration

​
zodSchema
ZodTypeAny
required
Any Zod schema — z.object, z.array, z.string, z.union, or any composition thereof. Pass it as the first argument to gates.schema(...).
​
target
"output" | "input"
Which field of the evaluation context to validate. Defaults to "output". Set to "input" to validate what the agent received rather than what it produced.
​
name
string
Override the gate name recorded in results. Defaults to "schema".

​
Validating a flat string response

The schema gate works on any Zod type, not just objects: 
import { createEngine, gates } from "@pecta/core";
import { z } from "zod";

const engine = createEngine({
  gates: [
    gates.schema(z.string().url(), { name: "schema.url" }),
  ],
});

const result = await engine.evaluate({
  agent_id: "link-bot",
  output: "not-a-valid-url",
});
// result.passed === false
// reason: "schema validation failed (1 issue): <root>: Invalid url"
Combine the schema gate with gates.content() to reject empty output before Zod runs. Because the engine runs gates in parallel by default, both gates evaluate simultaneously — but with failFast: true (the default), a content failure aborts the schema gate before it finishes if content fails first.