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.

nested_rulesets and filter_criteria are accepted in the configuration schema for forward compatibility, so operators can author them ahead of full support.

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.