Esquemas de salida para clientes

Una herramienta estructurada también puede anunciar un esquema de salida: un esquema JSON que indica a los clientes exactamente qué campos y tipos deben esperar.

Es una descripción legible por máquinas del resultado, que enumera el nombre y el tipo de cada campo. Los clientes la leen antes de llamar a la herramienta.

Cuando devuelve un modelo de Pydantic, el SDK deriva automáticamente el esquema de salida. Sus anotaciones de tipo se convierten en el contrato publicado.

El esquema se incluye en la lista de herramientas, bajo outputSchema. Un cliente que inspeccione las herramientas conoce la estructura sin tener que probarla.

Con un esquema conocido, un cliente puede validar los resultados y preparar la interfaz de usuario. Ya no tiene que adivinar qué campos aparecerán.

El esquema marca temp_c como un número y condition como una cadena. Los consumidores confían en estos tipos en lugar de inferirlos a partir de un único ejemplo.

Los campos con valores predeterminados se vuelven opcionales en el esquema; los demás son obligatorios. Los clientes saben qué claves tienen la garantía de estar presentes.

Trate el esquema de salida como una promesa. Cuando los clientes dependan de él, cambiar los nombres o tipos de los campos puede romperlos posteriormente.

Los clientes estrictos validan cada resultado según el esquema y rechazan las discrepancias. Esto detecta rápidamente los errores del servidor, en el límite.

Un esquema de salida también sirve como documentación. Los nuevos desarrolladores leen el esquema para entender una herramienta sin tener que revisar su código.

Asegúrese de que su herramienta siempre devuelva lo que declara el esquema. Un resultado que se aleja de su esquema debilita la confianza que los clientes depositan en él.

Ha visto cómo una herramienta publica un esquema de salida de su modelo. Documenta los campos, permite la validación y establece un contrato estable. ✅