Llamar a la API de TypeSafe desde un agente: forma de la solicitud, errores, reintentos y fijación de versión

Objetivo

Realizar una primera llamada correcta, gestionar los estados de fallo documentados y mantener los resultados reproducibles entre versiones del modelo.

Requisitos previos

Una clave de API de la consola del proveedor (acceso anticipado en el momento de escribir esto), exportada como TYPESAFE_API_KEY, que ambos SDK oficiales leen por defecto. Python: pip install typesafe-sdk o uv add typesafe-sdk. JavaScript (Node.js 20 o posterior): npm install @typesafe-ai/sdk. El HTTP directo funciona sin SDK.

Pasos

1. Construir la solicitud: POST https://api.typesafe.ai/v1/systemone con Authorization: Bearer <key> y un cuerpo JSON con state (cadena, objeto o array), model (jev-latest o un identificador versionado como jev-1.13.0) y questions, un mapa de una clave elegida libremente a una pregunta tipada (type de noul, choice o score, instructions y criteria según lo exija el tipo).
2. Leer la respuesta: model (el identificador versionado que respondió), answers bajo las mismas claves (un valor noul; o choice, probabilities y confidence; o score, legend, probabilities y confidence) y usage con input_tokens y output_tokens. En el SDK de Python, las mismas respuestas son accesibles como response.nouls[...], response.choices[...] y response.scores[...].
3. Gestionar los errores según el código de estado: 401 indica una clave ausente o inválida; 422 indica que el cuerpo no superó la validación, y el propio cuerpo indica el campo; 429 indica que se superó un límite de tasa; 529 indica que el servicio está sobrecargado. La referencia indica reintentar 429 y 529 con backoff exponencial, nunca de inmediato.
4. Al usar el SDK de Python, conviene conocer sus valores por defecto: una RetryPolicy con dos reintentos, backoff inicial de 0.5 s hasta 5 s con jitter, estados reintentables 408, 429 y 5xx, respect_retry_after activado y un tiempo de espera de 30 s; se puede sobrescribir cuando el plazo propio del agente sea más corto.
5. Mantenerse dentro de los presupuestos documentados: 64k tokens por solicitud, 32k para el estado más la pregunta más larga, como máximo 255 opciones de Choice y 10 niveles de Score. Superarlos produce un 422, no una respuesta truncada.
6. Fijar el modelo una vez ajustados los umbrales: los alias cambian con cada versión; GET /v1/models lista los alias que la cuenta puede enviar, y los identificadores versionados se aceptan aparezcan o no en esa lista.
7. Para un agente de codificación, instalar la skill del proveedor (<coding-agent> plugin marketplace add typesafe-ai/skills y <coding-agent> plugin install typesafe@typesafe-ai para el agente de codificación, npx skills add typesafe-ai/skills --skill typesafe-ai en otros casos) y actualizarla antes de usarla; el proveedor atribuye los campos de solicitud o de respuesta inventados a una skill desactualizada.

Resultado esperado

Una solicitud que valida a la primera, un cliente que aplica backoff ante 429 y 529 sin saturar el endpoint, y registros que identifican el modelo versionado detrás de cada decisión.

Límites y base de verificación

Todo lo anterior es la documentación del proveedor a fecha de septiembre de 2026; se indica que los límites de tasa pueden cambiar sin previo aviso durante el acceso anticipado, por lo que conviene tratar el 429 como algo esperado y no excepcional. No se afirma ninguna medición de latencia ni de precisión.