Distingue cinco objetos en tu integración. La sesión autoriza llamadas públicas al entorno de ejecución y la conversación agrupa mensajes. El flujo transmite lo que ocurre durante un turno. Un archivo es una entrada identificada por una referencia pública; un artefacto es un resultado duradero. Cada uno tiene su propio ciclo de vida y afecta de forma distinta a la interfaz.
Esta vista general muestra los límites de sesión y errores; el ciclo documentado añade conversaciones, archivos y resultados.
Elige el objeto adecuado para cada tarea
Desplázate horizontalmente para ver todas las columnas.
| Objeto | Función en la integración | Qué decisión no toma |
|---|---|---|
| Sesión | Guarda los metadatos públicos de la sesión y el token utilizado en las llamadas al entorno de ejecución. | Qué conversación ve la persona. |
| Conversación | Agrupa mensajes bajo una conversationRef. | Si terminó un turno nuevo. |
| Flujo | Emite eventos como fragmentos de mensajes, finalización, interacciones y errores. | Si la aplicación puede ignorar una aprobación pendiente o una interrupción. |
| Archivo | Entrada cargada con anterioridad, a la que se hace referencia con fileRef. | Si la política vigente permite que el agente lo lea. |
| Artefacto | Resultado duradero que se puede recuperar con artifactRef. | Cómo debe representar la aplicación todos los tipos posibles de resultado. |
Sigue una revisión de documento
Imagina que un portal de operaciones recibe inspection-notes.pdf y pide al agente que resuma la condición descrita. Primero, lee la política pública filePolicy. Comprueba los permisos upload, los tipos MIME permitidos y el tamaño máximo antes de enviar el contenido. La documentación indica que el cuerpo de la carga usa base64; no hay un flujo separado de carga multipart ni mediante una URL firmada. Un archivo nuevo puede tener el estado processing antes de estar available, así que no trates esos estados como equivalentes.
Después de cargarlo, pasa el fileRef devuelto en streamMessage({ fileRefs }) para ese turno. La documentación del SDK no describe otro objeto tipado de adjuntos para el turno, aparte de estas referencias públicas. Durante la transmisión, agrega cada message:delta al borrador visible en vez de reemplazar el texto anterior. Trata message:complete como el evento que contiene el contenido final y los resultados públicos relacionados. El evento artifact:created puede llegar antes de que termine el turno; el evento de finalización también puede incluir artefactos.
Revisión de documento completada (portal ficticio)
Entrada: Terminó de cargarse
inspection-notes.pdfcon el estadoavailable; sufileRefpúblico se adjunta al turno.Conversación: El turno está asociado con la
conversationRefactual.Resultado del flujo:
message:completedevuelve un resumen y una referencia a un artefacto para una tabla de revisión.Estado de la interfaz: El resumen aparece como completo; la tabla se abre con
getArtifact()y hay un método de representación alternativo por si no existerenderHints.
El ejemplo supone que el agente puede leer el archivo cargado y está configurado para producir ese artefacto. Comprueba la política antes de mostrar controles para archivos o artefactos. Las operaciones con archivos de la biblioteca de contexto son un caso separado: requieren tanto un binding de espacio de trabajo materializado como el soporte de la política.
Representa solo lo que confirman los eventos
Cuando no necesitas mostrar el texto token a token, collectAssistantMessage() puede consumir el flujo y devolver el mensaje ensamblado, junto con cualquier uso, referencia, archivo o artefacto generado. Los renderHints de un artefacto son metadatos orientativos de presentación, no un contrato de representación; prepara una alternativa segura. Comprueba que la capacidad de artefactos esté habilitada antes de recuperarlos y trata una referencia fuera de los límites como no disponible, sin probar otras sesiones o espacios de trabajo.
Para conocer las conversaciones, la cancelación, las interacciones y los tipos de eventos, consulta conversaciones y streaming. Continúa con archivos y artefactos, sesiones y almacenamiento y espacios de trabajo y agentes externos.