Rule Validator Agent

The Rule Validator Agent (rule_validation) checks documents and data against a set of business rules you define and emits a verdict for each rule — pass/fail for boolean rules, a constrained score for numerical rules — along with a plain-English rationale and the verbatim evidence the verdict rests on. Use it for compliance checks, document review, quality scoring, and any task where you need an auditable, rule-by-rule judgment rather than a single freeform answer.

The Rule Validator Agent belongs to the Frequently Used group in the agent library.

Three things define how this agent behaves:

• Per-rule output. Every rule gets its own verdict, rationale, and evidence list. Downstream nodes and dashboards render the array directly.
• Boolean and numerical rules are both first-class. A numerical rule emits an integer score drawn from a set you constrain.
• Typed inputs land in the user message, never in the Instructions. Documents and named inputs are wrapped in document markers so the model reads each one as a discrete piece of evidence — they are never folded into the system prompt.

Configuration

You configure the agent through agent_config.type_config. The required field is rules.

{
  "id": "contract_review",
  "type": "boolean",
  "rules": [
    {
      "rule_id": "R1",
      "rule_text": "The contract is signed on the final page.",
      "type": "boolean"
    },
    {
      "rule_id": "R2",
      "rule_text": "Rate the completeness of the liability section from 0 to 5.",
      "type": "numerical",
      "numerical_rule_config": { "possible_scores": [0, 1, 2, 3, 4, 5] }
    }
  ]
}

Per-rule fields

A numerical rule must resolve to a non-empty score set — either through its own possible_scores or through the ruleset's global_numerical_rule_config (which materializes a range from min_score to max_score by increment). A node whose numerical rule has neither is rejected with a validation error.

Aggregation modes

When you set boolean_aggregation or numerical_aggregation on the ruleset, the agent rolls the per-rule verdicts up into a single ruleset-level result alongside the flat rules array. Rules marked not-applicable are excluded from the boolean denominator; numerical rules with insufficient data are excluded from the numerical aggregate.

Beyond the modes above, boolean_aggregation also accepts custom (paired with a boolean_aggregation_expression), and numerical_aggregation also accepts min and max.

nested_rulesets and filter_criteria are fully evaluated at run time: nested rulesets are scored recursively and aggregated bottom-up (depth-capped), and filter_criteria prune non-matching rulesets and rules against the supplied named_inputs before any rule runs.

Inputs

Rule Validation takes typed inputs. All fields are optional, but at least one must be provided — the agent has nothing to evaluate otherwise.

Documents are wrapped in <------- Start of Document: name -------> markers in the user message so the model treats each as discrete evidence. When named_inputs is absent, any other top-level input key is auto-promoted into a named input so workflows can wire individual scalar fields without hand-assembling an array.

Input example

{
  "primary_docs": [
    { "file_name": "MSA-Acme.pdf", "content": "Master Services Agreement..." }
  ],
  "named_inputs": [
    { "name": "contract_value", "value": 250000 }
  ]
}

Output

The output is a JSON object with a rules array — one entry per configured rule, keyed by rule_id, in the same order as your rules list.

{
  "rules": [
    {
      "rule_id": "R1",
      "data_sufficiency": true,
      "rationale": "The agreement carries a signature block initialed on page 14.",
      "boolean_output": true,
      "not_applicable": false,
      "evidences": [
        { "text": "Signed: J. Smith, page 14", "source_origin": "MSA-Acme.pdf", "source_page_number": 14 }
      ]
    },
    {
      "rule_id": "R2",
      "data_sufficiency": true,
      "rationale": "The liability section covers caps and carve-outs but omits indemnity.",
      "numerical_output": 3,
      "not_applicable": false,
      "evidences": [ ... ]
    }
  ]
}

Each evidence whose source_origin matches a supplied document produces a cited source on the response (deduplicated by origin, text, and page). A best-effort repair pass re-anchors paraphrased snippets to verbatim document spans.

Validation behavior

The agent validates the model's output and retries (within the output-retry budget) with a corrective prompt when it finds a recoverable problem — malformed JSON, a code-fenced response, a missing or duplicated rule_id, a missing rationale, a boolean rule missing boolean_output, or a numerical score outside the allowed set. The per-rule output is re-ordered to match your configured rule order before it's returned.

Excel report

When type_config.generate_report is true and the service has blob storage configured, the agent renders an Excel (.xlsx) validation report — a title row, summary statistics, and a per-rule row with pass/fail and score cells — and uploads it. The report descriptor appears on the response as validation_report (file name, URI, MIME type, and a tenant-relative reference_id). The file is downloaded through a tenant-scoped endpoint:

GET /rule-validation-reports/{reference_id}     # JWT-authenticated (user)
GET /internal/rule-validation-reports/{reference_id}   # internal

Tenant scoping is derived from the verified auth context, never from the path, so a report uploaded by one tenant is unreachable to another.

Long-running execution

Rule validation is a read-only, potentially long-running type, so it can run on the asynchronous execution path (POST /internal/execute-async) — the agent returns a job handle and posts the result back when finished. See the Agent Reference overview.

What's next

• Agent Reference overview — how agents work, the catalog, the four builder groups, and the shared execution engine.
• Data Extractor Agent — turn unstructured text into schema-conforming JSON.
• Custom Agent — build a general-purpose agentic agent with Tools and an output schema.