Módulo 08
Interfaces estructuradas y contratos de herramientas
- Fase del proceso:
- Construir
- Nivel de competencia:
- Ingeniería
- Tiempo estimado:
- 9-11 horas
- Requisitos previos:
- Ingeniería de sistemas de prompts
Construye límites tipados y robustos entre las salidas probabilísticas del modelo y el software determinista. Para eso usarás las salidas estructuradas nativas, esquemas, contratos de funciones y herramientas, validación y, cuando convenga, decodificación restringida.
Al terminar este módulo sabrás
- Distinguir entre un JSON válido, una salida válida según el esquema, una salida semánticamente correcta y una salida segura.
- Diseñar contratos tipados de herramientas y funciones, con descripciones claras, restricciones en los argumentos y una semántica de errores definida.
- Usar la salida estructurada nativa del proveedor cuando exista, y entender la decodificación restringida por gramática para la inferencia propia.
- Diseñar reintentos acotados y validadores deterministas, sin bucles de "reparación" infinitos.
Qué vas a producir: Especificación de interfaces (contratos de herramientas al estilo de JSON Schema/OpenAPI): Contratos de herramientas de lectura y de escritura, con sus parámetros, si modifican datos, idempotencia, autorización y semántica de errores. Se guarda en tu Cuaderno de Ingeniería como evidencia de lo que sabes hacer.
Lecciones
8.1 Garantías de la salida estructurada
Las salidas nativas restringidas por un esquema y sus límites: cumplir el esquema no es acertar en los hechos.
Punto de práctica: Genera salidas restringidas por un esquema y, después, crea a propósito ejemplos que cumplan el esquema pero sean semánticamente incorrectos.
8.2 Diseño de contratos de herramientas y funciones
Capacidad, parámetros, restricciones, semántica de lectura y escritura, idempotencia, contexto de autorización y errores.
Punto de práctica: Rediseña una herramienta vaga `manage_customer()` como herramientas de lectura y de actualización con un alcance estrecho.
8.3 Decodificación restringida por gramática
Los conceptos de gramática (CFG) y máscara de tokens, y herramientas como XGrammar u Outlines para la inferencia propia.
Punto de práctica: Ejecuta un ejemplo de generación restringida en local o con un motor de gramáticas simulado, y comprueba que las rutas de sintaxis imposibles quedan bloqueadas.
8.4 Patrones de validación y reparación
Validación de esquema y de dominio, errores tipados, reintentos acotados, alternativas y escalado a una persona.
Punto de práctica: Implementa un resultado con tres estados: válido, reintentable y no reintentable/escalar.
Laboratorio: Extracción tipada y contrato de herramienta
Partes de un prompt que pide JSON sin más y migras a una salida restringida por un esquema, con validación determinista.
Se ejecuta en Google Colab: sin instalar nada y sin API key.
Ver el notebook en Colab (se abre en una pestaña nueva)Reto de ingeniería
Diseña el contrato de una herramienta de órdenes de compra que no pueda superar los límites aprobados de cantidad y precio, ni hacer una escritura sin evidencia explícita de autorización.
Artefacto: Especificación de interfaces (contratos de herramientas al estilo de JSON Schema/OpenAPI)
Control de competencia
100% de conformidad con el esquema en el conjunto adversarial público; las pruebas semánticas PASAN.
- TOOL-01 La salida es válida según el esquema (crítico)
- TOOL-02 El validador de dominio detecta los datos semánticamente inválidos
- TOOL-03 Se declara si la herramienta modifica datos
- TOOL-04 Las escrituras exigen un campo de autorización (crítico)
- TOOL-05 El bucle de reintentos está acotado
Referencias
- [R13]OpenAI API - Structured Outputs (se abre en una pestaña nueva): OpenAI; revisado el 2026-09-28
- [R18]Enterprise Prompt and Context Engineering: An Engineering Design Process Curriculum for Foundation Model Systems (2026 Edition): User research (source document supplied to this project); revisado el 2026-09-28