Empieza por la primera comprobación que falla en el flujo de integración. Revisa la autenticación y la aserción firmada, la política pública vigente, el estado de la sesión, la disponibilidad del espacio de trabajo cuando haga falta y la entrada o el evento de stream concreto. Antes de reintentar, averigua si la solicitud falló, espera la intervención de una persona o ya terminó.
El diagrama señala el navegador, el servidor, el agente, la sesión, el resultado y la ruta de error. Usa esos límites para ubicar el síntoma antes de cambiar la integración.
Localiza el primer límite que falla
Desplázate horizontalmente para ver todas las columnas.
| Límite y síntoma | Evidencia que debes revisar | Siguiente paso seguro |
|---|---|---|
| Autenticación: no hay sesión | Confirma que la persona usuaria llega al endpoint de aserción y que la función de retorno devuelve una cadena de aserción firmada. | Corrige la autenticación o la generación de aserciones en el servidor; conserva allí la credencial de firma. |
| Política: control ausente o denegado | Comprueba los indicadores de capacidad vigentes, los campos de política pertinentes y cualquier ajuste negociado que se haya devuelto. | Oculta los controles no disponibles; una denegación estable unsupported_capability no es un resultado vacío. |
| Sesión: estado ausente o desactualizado | Comprueba los métodos de sesión y los metadatos de sessionRef; revisa por separado el conversationRef activo en el estado de la aplicación. | Verifica cada referencia en su propio límite; sigue el ciclo de vida de la sesión para renovarla o revocarla. No registres el token portador. |
| Espacio de trabajo: acción duradera bloqueada | Comprueba que la tarea necesite un espacio de trabajo, las capacidades concedidas y el estado del runtime. | La guía vigente no requiere uno para chat, streaming ni artefactos de un turno; para las tareas que sí lo necesitan, espera durante el aprovisionamiento y trata failed: true como terminal. |
| Entrada: contexto o archivo rechazado | Comprueba los campos de host aceptados y el límite de bytes; para archivos, revisa política, tipo, tamaño y estado. | Envía campos planos permitidos; espera a que el archivo esté available antes de adjuntar su fileRef compatible. |
| Stream: turno incompleto | Comprueba la finalización, el campo retryable de un evento error, las interacciones o aprobaciones pendientes y las interrupciones. | Mantén abiertos los estados pendientes; reintenta solo si el error y la operación permiten repetirla de forma segura, y concilia primero los resultados inciertos. |
Estas comprobaciones provienen de las guías de integración vigentes. El orden ayuda a acotar la búsqueda, pero no garantiza que cada síntoma tenga una sola causa. Registra el método público, los campos de política pertinentes, el tipo de evento y los indicadores del runtime, sin guardar tokens de portador, aserciones, entradas privadas ni identificadores internos sin filtrar.
Comprueba el contrato de entrada, no solo la compilación
La guía de primeros pasos define hostContext como un mapa plano de valores primitivos. También muestra un caso específico en el que un objeto anidado pasa la comprobación de tipos de las declaraciones del SDK, pero el servidor lo rechaza porque el valor no es público. Esto recuerda que las declaraciones de TypeScript y el contrato de ejecución de la solicitud responden a preguntas distintas. Consulta los campos actuales de hostContextPolicy.acceptedFields y el límite maxTotalBytes; envía solo los campos primitivos permitidos.
Registro de diagnóstico documentado (no es una reproducción en vivo)
Entrada de la llamada:hostContextcontienecustomer: { type: 'returning', value: true }.
Comprobación de compilación: La declaración actual acepta una estructura de objeto JSON.
Comportamiento descrito en la guía: La documentación de primeros pasos indica que los datos anidados{ type, value }se rechazan con400 host_context_field_not_public.
Diagnóstico: Que el tipo sea aceptado no valida la estructura del campo en tiempo de ejecución.
Siguiente comprobación: Compara las claves primitivas planas con los campos aceptados y el límite de bytes de la política vigente.
Este registro resume las declaraciones locales del SDK y la guía; no afirma que el artículo haya probado un runtime en vivo. Si una solicitud de producción se comporta de otra manera, conserva una reproducción mínima sin datos sensibles y pide a la persona responsable del SDK que verifique la implementación actual antes de documentar una corrección.
Distingue una denegación de un fallo que admite reintento
La documentación describe las capacidades desactivadas como denegaciones estables, no como respuestas vacías. Por tanto, una diferencia entre la política solicitada y la concedida indica un problema de configuración o de disponibilidad de la función, no una razón para reintentar a ciegas. Reintenta solo si el error público indica que se puede reintentar y la operación concreta está documentada como segura de repetir; si hay una acción pendiente o un stream interrumpido con resultado incierto, detente y concilia primero su estado. Del mismo modo, failed: true en un runtime de espacio de trabajo es terminal; un tiempo de espera al sondear o una espera cancelada significan otra cosa. Puede que un stream también esté esperando una aprobación o interacción en vez de estar averiado.
Registra el paso que falló, los campos de política, las referencias públicas, los valores booleanos del runtime y la categoría normalizada del evento o error. No recopiles tokens de sesión ni cadenas de aserción. Para conocer el ciclo de sesión, conversación y stream, consulta sesiones de agentes, conversaciones y artefactos; para ver la política, consulta políticas y capacidades de agentes externos, y para conocer el límite de confianza, lee referencias públicas y arranque seguro.