Agent Triage Handoff Schema

Machine-readable contract: /schemas/agent-triage-handoff.schema.json · Used by: triage-agent, troubleshooting-agent, shift-handover-agent

Full JSON Schema

The machine-readable contract is served at /schemas/agent-triage-handoff.schema.json. Key points: additionalProperties: false (unknown fields are rejected), required fields are issueSummary, intakeCompleteness, safetyStatus, recommendedRoute, advisorySummary, authorityLimits, escalationRequired, notAuthorizationStatement, and intakeCompleteness, safetyStatus, recommendedRoute, and the domainFlags items are constrained to enums.

This is the output side of triage: the Plant Issue Intake schema captures the messy input, the Plant Issue Intake & Triage template routes it, and this schema standardizes the advisory handoff the agent produces. It is a handoff contract, not an action plan — it records routing and limits, and authorizes nothing.

Valid example

A handoff that summarizes, flags, routes, and explicitly authorizes nothing. Values are qualitative placeholders — no setpoints, limits, or thresholds.

{
  "issueSummary": "Free lime reported trending up over recent samples; possible chemistry or sampling cause.",
  "intakeCompleteness": "partial",
  "safetyStatus": "no-immediate-flag-observed",
  "domainFlags": [
    "quality",
    "process",
    "data-quality"
  ],
  "recommendedRoute": "qc-out-of-trend-review",
  "retrievalTargets": [
    "/prompts/qc-out-of-trend-review",
    "/troubleshooting/high-free-lime",
    "/schemas/plant-issue-intake"
  ],
  "missingDataQuestions": [
    "Latest verified XRF oxides (for LSF/SM/AM context)?",
    "Free lime test method and whether the result was re-run?"
  ],
  "advisorySummary": "Confirm the result by re-sampling/re-running and verify instruments before drawing any conclusion, then review with QC and process engineering. No cause is concluded here.",
  "authorityLimits": [
    "Does not authorize any product release, hold, or rejection.",
    "Does not authorize any control, fuel/air, or feed change.",
    "Does not conclude a diagnosis or declare compliance."
  ],
  "escalationRequired": false,
  "humanOwner": "QC authority + authorized operations / process engineering",
  "notAuthorizationStatement": "Advisory only and not authorization. Release, control, and quality decisions require the appropriate human authority under site procedure."
}

Invalid example (and why)

This is what a handoff must not look like. It oversteps the advisory boundary in several ways.

{
  "issueSummary": "Free lime high.",
  "intakeCompleteness": "complete",
  "safetyStatus": "safe-to-continue",
  "recommendedRoute": "increase-burning-zone-temperature",
  "advisorySummary": "Raise the burning zone, release the current lot, and continue — the result is within permit limits.",
  "releaseDecision": "release the lot",
  "complianceStatus": "in compliance"
}

Why it fails:

• Authorizes action. recommendedRoute is a control change, not a route, and advisorySummary instructs an operation and a product release. A handoff routes to a human/template; it never tells anyone to operate, release, or change control.
• Declares safety and compliance. safetyStatus: "safe-to-continue" is a clearance (not an allowed enum value), and complianceStatus: "in compliance" is an environmental/permit determination — both belong to human authority, not the agent.
• Makes a release decision. releaseDecision is an extra field; with additionalProperties: false it is rejected, and a release/hold/reject decision is never the agent’s to make.
• Invents a limit. Claiming a result is “within permit limits” reproduces/asserts a threshold the contract forbids — the agent states no setpoints, limits, or acceptance criteria.
• Drops required fields. authorityLimits, escalationRequired, and notAuthorizationStatement are missing, so the not-authorization guardrails are absent.

Versioning

Semantic version in version. Additive changes (new optional fields) bump the minor version; any breaking change (new required field, removed/renamed field, tightened enum) bumps the major version and should ship under a new $id.