Ask for an object, then verify its meaning

The mechanism

Free-form text is useful for readers, but application logic needs explicit fields. Structured output asks the agent to produce an object that conforms to a schema. In the current Python API, pass structured_output_model to the invocation and read result.structured_output. The schema is a formatting and validation boundary; a well-typed answer can still contain an unsupported conclusion.

ParcelOps needs an incident summary with a status, evidence IDs and a next check. If the agent returns a convincing paragraph without evidence IDs, a downstream service should not have to guess which incident it describes. A narrow object also makes evaluation easier: each field can be checked independently.

A worked output contract

Optional inference when invoked. This fragment assumes agent is configured as in chapter 3, with the read-only lookup from chapter 5. Defining the Pydantic class itself does not call a model.

from typing import Literal
from pydantic import BaseModel, Field

class IncidentSummary(BaseModel):
    incident_id: str
    status: Literal["delayed", "resolved", "unknown"]
    evidence_ids: list[str] = Field(min_length=1)
    next_check: str = Field(min_length=1, max_length=300)

result = agent(
    "Look up INC-104 and return its observed status with evidence.",
    structured_output_model=IncidentSummary,
)
summary = result.structured_output
assert summary is not None
assert summary.incident_id == "INC-104"
assert set(summary.evidence_ids) <= {"INC-104"}

The last two assertions express application expectations for this synthetic case. They are not sufficient for arbitrary tenants or live records. A production verifier should compare evidence identifiers and observed values against trusted tool results from the same request. Merely checking that an ID has a familiar prefix proves very little.

The older Agent.structured_output() and async counterpart are deprecated in current documentation. Do not mix an old tutorial’s method with the invocation-based example and call that a tested migration. Record the API used and the SDK version in the environment card.

Practice: design invalid and misleading objects

Offline. Create four JSON fixtures: a valid delayed incident, an invalid status value, an empty evidence list and a structurally valid “resolved” incident whose source says “delayed.” Validate their shape with the schema, then write a separate domain check for the status mismatch.

Expected observation: the first and fourth can satisfy the same schema, while only the first is supported by the fixture. This is the central lesson. Schema validity reduces ambiguity at the interface; evidence checks establish whether the fields are justified. Add an explicit “unknown” option so the agent need not invent a value when evidence is absent.

Troubleshooting and trade-offs

If structured output fails, distinguish schema complexity, unsupported values, insufficient output budget and provider errors. Catch the SDK’s StructuredOutputException at the application boundary and return a controlled failure, not a half-parsed object. Avoid unbounded retry loops that repeatedly ask the same model to repair impossible constraints.

A schema with dozens of optional fields is difficult to evaluate and invites accidental ambiguity. Start with the smallest contract your consumer needs. Version it when semantics change, even if field names remain the same. For example, changing “status” from observed status to predicted future status is a breaking semantic change despite identical JSON types.

Interview practice

Completion check

Show one object that passes schema validation but fails an evidence check. Explain how your consumer handles missing structured output and why retries need a finite policy.

Sources and version notes

Checked 6 October 2026. Python examples target strands-agents==1.58.0 unless labelled otherwise. Live documentation can change; compare your installed version before adapting an example.

• Current structured output API