Las salidas estructuradas facilitan la validación, la presentación y la derivación de los resultados de un agente. Define los campos obligatorios, los valores permitidos, cómo representar los datos desconocidos, qué fuentes respaldan el resultado y cuándo debe revisarlo una persona. Después, valida la estructura y, por separado, comprueba que los valores coincidan con evidencia autorizada antes de que otro sistema dependa de ellos.
La ficha define la tarea. El contrato JSON que sigue especifica qué debe contener el resultado.
Define el resultado antes de elegir cómo mostrarlo
Para un flujo ficticio de estado de pedidos, exige los siguientes campos. Sus nombres y valores enumerados forman el contrato de ejemplo de este artículo; no son un tipo del SDK ni una API de AgentShelf:
Desplázate horizontalmente para ver todas las columnas.
| Campo | Contrato para este flujo |
|---|---|
order_ref | Cadena obligatoria que debe coincidir con el registro de pedido autorizado. |
ownership_verified | Booleano obligatorio; solo es true después de confirmar que el cliente con sesión iniciada coincide con la persona propietaria del pedido. El número de pedido por sí solo no demuestra que tenga acceso. |
status | Enumeración obligatoria: in_transit, delivered, delayed o unknown. |
last_scan | Objeto obligatorio con location y time, o null si no hay un escaneo disponible. |
delivery_estimate | Cadena obligatoria tomada de la fuente, o null cuando la fuente no proporcione una estimación. |
customer_message | Borrador en lenguaje claro y obligatorio, respaldado por los demás campos. |
review_required y review_reason | Indicador obligatorio y motivo anulable; solicita revisión si falla la verificación de titularidad, la evidencia se contradice o el estado es desconocido. |
source_refs | Lista obligatoria de referencias a los registros aprobados utilizados. |
Este contrato permite representar un dato desconocido en vez de incentivar una conjetura. Mantén la tarea en modo de solo lectura: producir una respuesta sobre el estado no autoriza a modificar un pedido, emitir un reembolso ni prometer una fecha de entrega.
El número de pedido por sí solo no demuestra que exista permiso de acceso. Primero verifica la titularidad de la persona con sesión iniciada mediante el contexto de identidad confiable de la aplicación; solo después consulta el registro de seguimiento. Si no se confirma la titularidad, detente antes de leer el registro y usa una respuesta de acceso denegado o una derivación a soporte que no revele detalles del pedido. El campo ownership_verified informa de esa comprobación confiable; un booleano generado por el modelo no concede acceso.
Valida por separado la estructura y la evidencia
Primero valida la estructura: que estén todos los campos obligatorios, coincidan los tipos, se permitan los valores enumerados y los campos anulables contengan el valor documentado o null. Rechaza los resultados mal formados; no muestres una respuesta parcial ni conviertas un valor enumerado desconocido en un estado de éxito. Verifica la titularidad antes de consultar el seguimiento; si falla, no consultes ni reveles el registro.
Después valida el significado con respecto a la entrada y a la fuente aprobada. Comprueba que la cuenta con sesión iniciada sea titular del pedido, que la referencia de la fuente identifique el registro de seguimiento consultado y que el estado y los datos del escaneo coincidan. Confirma que una estimación nula siga siendo nula en el mensaje al cliente. Un objeto JSON válido según el esquema todavía puede contener una afirmación sin respaldo o que no coincide con la fuente; validar solo la estructura no basta.
Revisa un resultado completado
En este ejemplo ficticio, antes de consultar el seguimiento, el sistema confirma mediante un contexto de identidad confiable que el cliente con sesión iniciada es titular del pedido O-418. Solo después de esa comprobación lee el registro de seguimiento aprobado: indica que el paquete está en tránsito, se escaneó por última vez en el centro de distribución Norte a las 09:40 y no incluye una estimación de entrega. Si no se confirma la titularidad, el flujo se detiene antes de leer el registro y devuelve una denegación segura o deriva el caso sin revelar datos del pedido. Cuando sí se confirma, permite una consulta de solo lectura y un borrador de mensaje.
Resultado JSON ilustrativo: solo contrato de salida, no es una solicitud del SDK ni de la API
Comprobación de entrada: El contexto de identidad confiable confirma que el cliente es titular; solo entonces se consulta el registro de seguimiento aprobado.
Resultado validado:{ "order_ref": "O-418", "ownership_verified": true, "status": "in_transit", "last_scan": { "location": "Centro de distribución Norte", "time": "09:40" }, "delivery_estimate": null, "customer_message": "El pedido O-418 está en tránsito. El último escaneo fue a las 09:40 en el centro de distribución Norte. El registro de seguimiento no incluye una fecha estimada de entrega.", "review_required": false, "review_reason": null, "source_refs": ["tracking-record-O-418"] }
El resultado coincide con el registro descrito, conserva como null la estimación faltante y no afirma que se haya escrito ningún dato ni que exista una fecha de entrega confirmada. Si no se puede verificar la titularidad, hay evidencia contradictoria o falla la validación de la estructura, no envíes el borrador como respuesta verificada: deriva el caso a revisión. Mantén la validación y cualquier acción comercial posterior como pasos independientes.
Para definir los límites de la tarea y redactar un encargo conciso, continúa con cómo definir una tarea enfocada para un agente. Para decisiones que requieren revisión humana, consulta agentes de IA con supervisión humana; para el ciclo de vida de la conversación, lee sesiones, conversaciones y artefactos.