Agent Structured Output & Format Adherence: When Your Agent Promises JSON but Delivers Poetry

Format Failure Taxonomy

1. The "Wrapper" Problem

Agent is told: "Output ONLY valid JSON. No other text." Agent outputs:

Wrapped in a Markdown code block with backticks. The user's JSON parser chokes. The agent added formatting that makes the output machine-unreadable. The wrapper problem is the #1 structured output failure — the agent can't resist adding conversational framing.

Measure: Raw format adherence — does the agent output exactly what was requested with zero framing?

2. The "Schema Drift" Problem

User specifies output schema: {name: string, price: number, features: string[]}. Agent outputs: {product_name: "Gobii", cost: 29.99, capabilities: ["AI agents", "MCP"]} — different field names, wrong types. The agent understood the intent but not the schema. Schema drift makes structured output unreliable for downstream processing — every field must be manually verified and mapped.

Measure: Schema adherence — do field names, types, and structure match the specification?

3. The "Incomplete Output" Problem

Agent is asked for 20 items in JSON. It outputs 14 items, then: "...and 6 more similar items." The agent truncated the output because it was getting long. The output is incomplete and the truncation is informal — there's no way to programmatically detect it.

Measure: Output completeness — does the agent produce all requested items?

4. The "Nested Hell" Problem

Agent outputs deeply nested JSON where flat was requested: {data: {results: [{item: {details: {pricing: {monthly: 29.99}}}}]}} instead of {name: "Gobii", monthly_price: 29.99}. The agent's internal data representation leaked into the output. The user must write complex parsing logic to extract simple fields.

Measure: Output normalization — is the output flat and predictable?

5. The "Format Switching" Problem

User: "Output as CSV." Agent outputs 3 rows of CSV, then switches to a bulleted list for "additional notes." The CSV parser fails on row 4. The agent can't maintain a single output format for the entire response.

Measure: Format consistency — does the agent maintain the same format from first character to last?

The "Output Channel Separation" Problem

Agents have two output channels: conversation (talking to the user) and data (delivering structured results). They constantly mix them. The solution: separate output channels. "I'll put your data in the data channel and use the conversation channel for discussion." Most frameworks don't support this. The agent that can separate channels delivers clean data. The agent that can't delivers conversational JSON.

Measure: Output channel separation capability — can the agent cleanly bifurcate conversation from structured data?

The "Structured Output Validation" Gap

Does the agent validate its own structured output? After generating JSON:

• Does it parse the JSON to verify validity?
• Does it check field names against the schema?
• Does it verify types?
• Does it confirm all required fields are present?

The agent that validates its output catches 80% of format errors before the user sees them. The agent that doesn't delivers broken JSON with confidence.

Measure: Self-validation rate on structured output.

The "Format Flexibility" Spectrum

Format	Primary Failure Mode	Reliability Notes
JSON	Wrapper, schema drift, incomplete	Most common, most error-prone
CSV	Format switching mid-output	Parser fails on conversational rows
Markdown Tables	Alignment, escaping, column drift	Column count shifts mid-table
YAML	Indentation errors	Whitespace-sensitive format breaks silently
XML	Tag matching, encoding	Unclosed tags break parsers
Code	Language detection, syntax	Wrong language fence, incomplete blocks

The agent that supports many formats reliably is a data integration tool. The agent that's unreliable on JSON is a chat bot.

Measure: Format reliability matrix — accuracy rate per format.

Cross-Framework Structured Output Benchmark

30 tasks: 10 JSON (varying complexity), 5 CSV, 5 Markdown tables, 5 mixed format (JSON + explanation), 5 schema-adherence (must match exact schema).

Metrics: Raw format adherence, schema adherence, output completeness, format consistency, self-validation rate.

Deliverable: "Agent Structured Output Scorecard" comparing format reliability, schema adherence, output channel separation, and format flexibility across frameworks.