Structured outputs make an agent result easier to validate, display, and route. Define required fields, allowed values, how the agent represents unknown facts, which sources support the result, and when a person must review it. Then check the output’s shape and separately check that its values match authorized evidence before another system relies on it.
The brief defines the job. The JSON contract below specifies what its output must contain.
Define the result before choosing how to render it
For a fictional order-status workflow, require the following fields. The exact names and enum values are an example contract for this article, not an SDK type or AgentShelf API:
Scroll horizontally to see all columns.
| Field | Contract for this workflow |
|---|---|
order_ref | Required string matching the authorized order record. |
ownership_verified | Required boolean; true only after the signed-in customer is matched to the order owner. An order number alone is not proof of access. |
status | Required enum: in_transit, delivered, delayed, or unknown. |
last_scan | Required object with location and time, or null when no scan is available. |
delivery_estimate | Required string from the source, or null when the source gives no estimate. |
customer_message | Required plain-language draft supported by the other fields. |
review_required and review_reason | Required flag and nullable reason; set review when ownership fails, evidence conflicts, or the status is unknown. |
source_refs | Required list of references to the approved records used. |
This contract makes the unknown case representable instead of encouraging a guess. Keep the task read-only: producing a status response does not authorize an order change, a refund, or a delivery commitment.
The order reference alone is not proof of access. First verify the signed-in customer’s ownership through the application’s trusted identity context; only then look up the tracking record. If ownership is not confirmed, stop before reading the record and use a separate safe denial or support handoff that reveals no order details. The ownership_verified output reports that trusted check; a model-generated boolean cannot grant access.
Validate shape and evidence separately
First validate the structure: required fields exist, types match, enum values are allowed, and nullable fields contain either the documented value or null. Reject malformed output rather than displaying a partial result or mapping an unknown enum to a success state. Run the ownership check before the tracking lookup; do not query or reveal the record when it fails.
Then validate meaning against the input and approved source. Check that the signed-in account owns the order, that the source reference identifies the retrieved tracking record, and that the status and scan details match it. Confirm that a null estimate remains null in the customer message. A schema-valid JSON object can still contain an unsupported or mismatched claim, so shape validation alone is not enough.
Inspect one completed result
In this fictional example, the signed-in customer is confirmed as the owner of order O-418. The approved tracking record says the package is in transit, was last scanned at the North distribution center at 09:40, and contains no delivery estimate. The workflow allows a read-only lookup and a message draft.
Illustrative JSON result — output contract only, not an SDK/API request
Input check: Customer ownership matches the order record; the approved tracking record is the source.
Validated result:{ "order_ref": "O-418", "ownership_verified": true, "status": "in_transit", "last_scan": { "location": "North distribution center", "time": "09:40" }, "delivery_estimate": null, "customer_message": "Order O-418 is in transit. Its latest scan was at the North distribution center at 09:40. The tracking record does not include an estimated delivery date.", "review_required": false, "review_reason": null, "source_refs": ["tracking-record-O-418"] }
The result matches the stated record, preserves the missing estimate as null, and does not claim a write or a confirmed delivery date. If ownership cannot be confirmed, evidence conflicts, or the structure fails validation, do not send the draft as a verified answer; return the case for review. Keep validation and any later business action as separate steps.
For task boundaries and a concise job brief, continue with how to define a focused agent job. For decisions that need human review, see human-in-the-loop agents; for the conversation lifecycle, read sessions, conversations, and artifacts.