# Agent9 Native Structured Output

<!-- auto-oncall-optimization-record
{
  "schemaVersion": "auto-oncall-optimization-record-v1",
  "optimizationId": "agent9-native-structured-output-2026-08-20",
  "problems": [
    {
      "problemId": "agent9-prompt-only-schema-allows-malformed-diagnostic-output",
      "summary": "The AOS Agent9 adapter described structured output only in prompt text, so a Scenario Diagnostic Agent could return readable but non-JSON output even though the same turn had an output schema.",
      "status": "candidate",
      "applicability": "Agent9-backed AOS turns that supply a Codex outputSchema, including Scenario Router, Scenario Diagnostic Agent, and Final Response Agent structured handoffs.",
      "issueKeys": ["ST-2865"],
      "sourceRefs": [
        "https://tidb.atlassian.net/browse/ST-2865#problem:agent9-structured-diagnostic-output"
      ],
      "signalTextIncludesAny": [
        "diagnostic_scenario_evidence_returned_non_json_output",
        "agent9 structured output malformed",
        "agent9 prompt-only output schema"
      ],
      "observedThrough": "2026-08-20",
      "effectiveAt": null,
      "verifiedAt": null,
      "attemptedAction": "Pass the existing Codex output schema through the Agent9 Turn input.outputSchema field without changing the prompt, and preserve clarification as a distinct non-answer outcome.",
      "evidenceUrl": null
    }
  ]
}
-->

- Optimization ID: `agent9-native-structured-output-2026-08-20`
- Owner: Agent9 transport adapter
- Source: ST-2865 passive Agent9 replay
- Implementation status: pending AOS PR and passive deployment
- Effective status: `candidate`

## Bounded problem

The passive Agent9 adapter previously appended a JSON Schema instruction to
the prompt but did not use Agent9's native structured-output field. In the
ST-2865 comparison, the capacity scenario completed while the workload
Scenario Diagnostic Agent returned non-JSON output and the runner recorded
`diagnostic_scenario_evidence_returned_non_json_output`.

This is a transport reliability gap. It does not change which Agent owns a
diagnosis, the schema itself, Provider execution, or any publication decision.

## Candidate change

- Preserve the original prompt byte-for-byte.
- Send the existing Codex SDK `outputSchema` as Agent9 Turn
  `input.outputSchema`.
- Keep ordinary unstructured Turns unchanged and omit the field.
- Treat an Agent9 clarification item as a clarification, not as a schema answer
  whose display text is passed to downstream JSON parsing.

## Verification status

Adapter contract coverage proves the exact native request body and the
structured-clarification boundary. Hosted PR checks, passive deployment, and a
case-specific replay have not completed, so this record remains `candidate`.

## Unresolved gaps

- Agent9 native structured output is deployed to internal prod, but the AOS
  passive adapter has not yet been delivered.
- No post-change ST-2865 replay has proved that both diagnostic scenarios reach
  ticket-level synthesis.

## Next validation action

Merge and deploy the passive AOS adapter, then replay ST-2865 with the same
historical cutoff and model. Compare it with the aligned Kubernetes result,
excluding Wetech OP from the acceptance criteria. Keep the record unverified
until the malformed structured-output signal is absent and the bounded case
criterion passes.