Apendice A: Lista de comprobacion previa al lanzamiento

Antes de que una función de IA llegue a los usuarios:

Frontera

• [ ] Proveedor detrás de un contrato; ninguna llamada al SDK del proveedor fuera del driver
• [ ] Credenciales resueltas por cliente, nunca sólo globales
• [ ] Una credencial ausente falla en voz alta al configurar, no en el proveedor
• [ ] Ninguna credencial de proveedor alcanzable desde el cliente

Salida

• [ ] Modo de salida estructurada activo donde exista
• [ ] Decodifica-o-lanza en el driver; validación de esquema donde se conoce el contexto del llamante
• [ ] Las rutas obligatorias son mínimas: sólo aquellas cuya ausencia corrompe algo
• [ ] Un fallo de análisis devuelve la forma esperada por el llamante, no null

Coste

• [ ] max_tokens fijado en el servidor, por propósito; el cliente no elige modelo ni tope
• [ ] Techo por cliente, incrementado antes de compararse
• [ ] Límite de frecuencia y presupuesto, atados a lo que paga y no a una credencial rotatoria
• [ ] Bloque de uso leído y registrado

Tiempo

• [ ] El turno corre fuera de la petición HTTP
• [ ] tries = 1; el reintento se decide por herramienta, no por job
• [ ] Tiempo de espera por llamada dentro de un plazo de reloj dentro del tiempo de espera del job
• [ ] failed() recupera estado parcial, fija done y limpia sus claves

Bucle

• [ ] Cada stop_reason tiene una rama; pause_turn manejado antes de la salida por «sin herramientas»
• [ ] El truncamiento se reporta y se muestra como error, nunca como respuesta
• [ ] Tope de iteraciones y presupuesto de reloj, ambos reportados cuando se agotan

Confianza

• [ ] Intentos contados contra el recurso, no contra el valor enviado
• [ ] Herramientas irreversibles protegidas por una restricción, no por una instrucción
• [ ] Tokens de un solo uso restaurados en todos los caminos de fallo
• [ ] Los mensajes de error no confirman nada a quien adivina
• [ ] Herramientas internas excluidas del conjunto publicado

Operación

• [ ] Versión del modelo fijada y registrada
• [ ] Registro por ida y vuelta: nombres y tamaños, nunca entradas
• [ ] Dependencias y capacidades nombradas; flujos cerrados antes de empezar
• [ ] Un camino al mismo resultado que no pase por el modelo

Apendice B: Lista de comprobacion para revisar un prompt

Para cualquier cambio en un prompt, una descripción de herramienta o una descripción de campo:

• [ ] ¿Está en control de versiones, en código, revisable como diff?
• [ ] ¿Toda prohibición lleva una acción alternativa?
• [ ] ¿Todo caso ambiguo resuelve a una salida definida y no al criterio del modelo?
• [ ] ¿Las instrucciones están atadas por nombre a los valores que describen?
• [ ] ¿Los identificadores internos están traducidos a palabras?
• [ ] ¿El contenido estable va primero, para que un prefijo se pueda cachear?
• [ ] ¿Las negativas emiten la misma forma que los aciertos?
• [ ] ¿Hay una prueba que compruebe que el prompt sigue declarando lo que el validador acepta?
• [ ] ¿Es un solo cambio, publicable y observable por sí mismo?

Apendice C: Lista de comprobacion de coste

• [ ] ¿Cuánto cuesta una llamada en el tope?
• [ ] ¿Cuánto cuesta un turno —llamadas multiplicadas por un historial que crece?
• [ ] ¿Cuál es el techo diario por cliente, y qué pasa al alcanzarlo?
• [ ] ¿El techo está atado a algo que no rota?
• [ ] ¿cache_read_input_tokens es distinto de cero? Si no, la marca de caché es decorativa
• [ ] ¿El esfuerzo de razonamiento está ajustado a esta función, o al valor por defecto pensado para problemas difíciles?
• [ ] ¿Cuál es el peor caso: iteraciones máximas, historial máximo, todas las herramientas llamadas?
• [ ] ¿Notarías ese peor caso ocurriendo mil veces antes de que llegue la factura?

Apendice D: La tabla de stop_reason

| Valor | Significado | Acción del bucle | El usuario ve | |---|---|---|---| | end_turn | Terminó | Salir, publicar | La respuesta | | (uso de herramienta) | Quiere una herramienta | Continuar, enviar resultados | Progreso | | pause_turn | Suspendido a mitad de turno | Continuar: reenviar historial | Progreso | | max_tokens | Salida cortada | Salir, reportar | Aviso de truncamiento | | refusal | La seguridad declinó | Salir, sin reintento | Una explicación clara |

Las dos que más se equivocan: pause_turn tratado como finalización porque no lleva llamadas a herramientas, y max_tokens cayendo por la misma rama que end_turn, con lo que una respuesta cortada se muestra como terminada.

Apendice E: Adonde ir despues

La documentación del propio proveedor, siempre, y con preferencia sobre cualquier cosa de este libro que la contradiga. Las APIs de modelos cambian en escalas de meses; las de un framework, en escalas de años. Cuando este libro muestra la forma de una petición, la forma es la lección y los nombres de los campos son una fotografía.

Todo lo demás que merece saberse está en un sistema que ya ejecutas. Mira qué hace tu función de IA cuando su proveedor va lento, cuánto cuesta en tu día de más tráfico y qué pasa si un usuario pulsa el botón dos veces. Las respuestas son más interesantes que cualquier cosa que yo pudiera poner en otro capítulo.