ValGuard.ai
Operations~8 min read

How to use self-healing without re-ask

Many production failures are small format problems, not wrong answers. The model returns JSON wrapped in a markdown fence, uses smart quotes, omits a comma, or sends a string where the schema expects a number. Validators treat that as a hard failure. The usual fix is a reask, which means another full LLM call, more tokens, and higher latency.

ValGuard response repair (self-healing) runs deterministic fixes on model output before validators execute. When repair succeeds, the response can pass validation without a retry.

This tutorial shows how to enable response repair on a high-traffic agent, verify that it reduces reasks without weakening quality gates, and keep strict rules on business-critical fields.

By the end, you will know:

  • where response repair sits in the validation pipeline,
  • which preset to start with (safe vs standard),
  • how to confirm repairs in request logs and response headers,
  • when to keep block instead of relying on repair.
UI note: In current UI you may see both labels: Playbooks and Orchestration (same section, depending on plan/version). Agent creation is in Dashboard -> Agents -> Create agent. If a guide mentions Validation logs, open Dashboard -> Logs and apply filters.

  1. 1How It Works

    Response repair is a deterministic step between the upstream model and your validators. The engine receives raw completion text, applies allowed Tier 1 and Tier 2 repair rules, then runs validation on the repaired output.

    Tier 1 fixes are structural: trim whitespace, extract JSON from markdown fences, normalize quotes, fix trailing commas, and similar syntax repairs. Tier 2 fixes are schema-aware: cast numeric or boolean strings, apply defaults, normalize enum casing, fuzzy-fix near-miss enums when enabled per field, parse locale-aware dates, normalize currency strings, and repair broken arrays when safe.

    If repair fixes the issue, validators see valid data and the request can complete without reask. That saves tokens and latency on failures that were technical, not semantic.

    Repair does not replace validation. It does not invent missing business facts or override policy rules. Use it for format drift, not for content quality.

  2. 2Prerequisites

    • Response repair enabled for your deployment (platform admin sets self_healing_enabled in system configuration on self-hosted setups; the Response Repair preset field appears on agent settings only when the feature is on)
    • An agent with output validators already configured
    • Access to Dashboard → Agents, Dashboard → Requests, and Dashboard → Validation logs
    • A baseline for the agent: request volume, reask rate, and average cost per request
    • A small set of recent failing payloads that often fail on JSON shape or type, not on business logic

  3. 3Step-by-Step Setup

    Step 1: Pick a high-traffic agent

    Open Dashboard → Agents and select an agent where format-related validator failures are common.

    Dashboard → Agents → list with selected high-traffic agent

    Start with one agent. Measure before you roll repair out broadly.

    Step 2: Enable a response repair preset

    Open Dashboard → Agents → [agent] → Settings. Find Response Repair preset.

    For a first rollout, choose Safe: Tier 1 structural. It covers fences, quotes, commas, and unquoted keys without aggressive inference. Move to Standard: Tier 1 + Tier 2 only after Safe looks stable on real traffic.

    Save the agent, then send a few known bad-format test payloads through the API or Playground.

    Agent settings → self-healing preset selector

    Workspace defaults live in Dashboard → Settings under debugging defaults. Agents set to Inherit workspace default follow the org preset.

    Step 3: Validate without changing validator policy

    Do not change validator on_fail settings in the same change window. You need a clean before/after comparison.

    Run test traffic and check:

    • how many requests would have reasked before repair,
    • how many pass after repair,
    • how many still block or reask because the underlying content is wrong.

    The goal is fewer technical retries, not higher pass rate on invalid business data.

    Step 4: Monitor request logs and headers

    Track repair impact over several days:

    • share of requests with repair applied,
    • reask count trend,
    • median latency,
    • cost per request.

    Open Dashboard → Requests and inspect recent completions. When repair ran, responses include debug headers such as X-VG-Healed, X-VG-Healed-Rules, and X-VG-Healed-Trace (when debug headers are enabled for the agent).

    Requests/Logs view with healed marker and reduced re-ask count

    Compare the same metrics in Dashboard → Validation logs for rules that previously drove reasks.

    Step 5: Keep strict rules on critical fields

    Leave business-critical validators as block or reask as appropriate. Examples: regulated identifiers, monetary amounts, authorization flags, and policy gates.

    Use repair for syntax and type normalization. Do not use it to bypass substantive validation failures.

  4. 4Configuration Examples

    Agent API fields (conceptual):

    {
  "slug": "invoice-extraction",
  "self_heal_preset": "safe",
  "max_reasks": 1,
  "validators": [
    { "name": "json_schema_validate", "on_fail": "block" },
    { "name": "required_fields", "on_fail": "reask" }
  ]
}

    Typical outcome:

    • Before: a trailing comma or fenced JSON body triggers required_fields or schema failure, then reask.
    • After: Tier 1 repair normalizes the payload, validators pass, no extra model call.

    Custom preset: set self_heal_preset to custom and enable specific rule IDs (for example tier1:extract_json_fence, tier2:cast_numeric) in self_heal_rules.

  5. 5Testing and Verification

    Verify in three layers:

    1. Fixture tests. Run known bad completions through the agent and confirm which repairs fire.
    2. Request logs. Confirm fewer reasks on the same traffic shape with stable block quality.
    3. Cost check. Compare token spend and latency before and after on the same agent.

    Add regression fixtures to CI using the test validators in CI/CD tutorial so preset changes do not widen repair scope silently.

  6. 6Troubleshooting

    "Reasks dropped, but business errors increased." Repair scope is too broad. Move from standard back to safe, or switch to custom with fewer Tier 2 rules. Keep critical validators on block.

    "No measurable cost improvement." Check whether failures were semantic, not format-related. Repair only helps when validators fail on syntax or type mismatch.

    "Some requests still reask." Expected. Repair does not fix missing fields or wrong content. Those requests should still follow normal on_fail behavior.

    "Response Repair preset is missing in settings." Confirm self_healing_enabled is on for the deployment and refresh the agent settings page.

  7. 7Best Practices

    • Roll out on one high-volume agent first.
    • Change preset and validator policy in separate releases.
    • Prefer safe, then promote to standard with metrics.
    • Separate technical validators (schema, required fields) from policy validators (PII, limits, approvals).
    • Keep shadow mode or staged rollout discipline when changing enforcement rules on production agents.

  8. 8Summary and Next Steps

    Response repair removes a common source of avoidable reasks: small format defects in otherwise usable model output. You keep strict validation while cutting retry cost and latency.

    Next tutorials:

What's next?