Skip to main content
Surface: GET /agents/runs/{id}, error.type = "AgentLoopSchemaDecodeFailed"

​
When this error occurs

When the model produces a final answer (no tool calls, just a content message), the workflow parses the content against the run’s output schema. This error means the parse failed:
  • Text mode (no output_format_schema supplied): the model’s response could not be decoded as the platform’s default text-bearing shape (a top-level text string).
  • Structured mode (output_format_schema supplied): the model returned JSON that did not conform to the caller’s schema — for example plain prose instead of a structured object, or an object missing a required field.
  • The model returned multiple text blocks; only the first is considered.

​
How to fix

  • Tighten the system prompt — explicitly tell the model “respond with a JSON object matching this schema; do not include any other text.” Models often add prose when the schema isn’t reinforced in instructions.
  • Simplify the schema — Bedrock’s structured-output sampler enforces a subset of Draft 2020-12; deeply nested or exotic constructs (e.g. unconstrained oneOf) are more likely to trip the decoder.
  • Increase max_tokens — sometimes the model is truncated mid-JSON.
  • Inspect the last assistant turn in the message stream to see exactly what the model produced.
Before V2026.x, every caller schema had to declare a top-level text: string because the workflow unconditionally extracted structuredOutput.text. That requirement is gone: structured-mode runs now return the caller’s schema verbatim on final_structured_output, and text-mode runs return a plain string on final_text. See Agent Conversations for the full response contract.