Política y capacidades de agentes externos

Lee la política pública de un agente externo antes de mostrar controles o iniciar un flujo. La política describe las capacidades, los perfiles de stream, los tipos de salida, los campos de contexto del host y las herramientas de dominio que expone el agente. Si llamas a prepare() con preferencias, basa la interfaz en el resultado negociado que devuelve el servidor, no en las opciones que solicitaste.

Revisa la política en el límite de integración con el servidor antes de mostrar una acción en la aplicación.

Inspecciona lo que expone el agente

Llama a getEffectivePolicy() para consultar el agente actual. Su estructura pública incluye indicadores de capacidad para mensajes, conversaciones, archivos, artefactos, interacciones y aprobaciones; perfiles de stream compatibles; tipos de módulos de salida; límites de archivos y de contexto del host; herramientas de dominio; límites de frecuencia y gasto; y el ajuste de detalle público de errores.

Organiza la interfaz en torno a las capacidades que requiere la tarea, no a la lista completa de métodos del SDK. Por ejemplo, un control para adjuntar archivos depende de la capacidad files del agente y de su filePolicy; un flujo que usa una herramienta de dominio depende del estado y los detalles de operación anunciados por esa herramienta. El servidor aplica las restricciones configuradas; la interfaz evita que las personas inicien una ruta no compatible y ofrece una explicación clara.

Usa los ajustes negociados

prepare() puede solicitar un perfil de stream, módulos de salida o la visualización de grounding del proveedor. El objeto negotiated que devuelve contiene los ajustes resueltos. Configura la vista con esos valores:

const { policy, negotiated } = await client.prepare({
  streamProfile: 'runtime-standard-v1',
  outputModuleTypes: ['citation'],
  providerGroundingDisplay: true,
});

renderWith(negotiated.streamProfile, negotiated.outputModuleTypes);

La guía del SDK describe runtime-standard-v1 como el flujo completo de eventos públicos del runtime, modules-v1 para módulos de salida estructurados y chat-legacy-v1 para compatibilidad con integraciones de chat anteriores. Trata estos nombres como las opciones documentadas para la versión actual del SDK; no supongas que el servidor aceptó una preferencia. Consulta la referencia de políticas para ver los tipos completos de los campos.

Diseña para las herramientas y las aprobaciones

Cada herramienta de dominio pública puede describir el tipo de operación, la clase de efecto secundario, la idempotencia, si requiere aprobación, sus esquemas y su estado. Una operación que requiere aprobación puede emitir un evento approval:requested durante el stream y esperar una decisión. Mantén visible ese estado pendiente. Una solicitud de aprobación, o una decisión aprobada, no demuestra por sí sola que la operación terminó; muestra el éxito solo cuando lo confirme el resultado de la operación.

Esta guía cubre la detección y presentación de aprobaciones. Las declaraciones del SDK de agentes externos 0.1.0 exponen eventos de aprobación, pero no especifican un método dedicado para resolverlas. La guía de conversaciones documenta respondToInteraction() para interacciones; no establece que se pueda pasar un approvalRef como interactionRef. Antes de habilitar controles de aprobación, verifica el flujo de resolución que admite la aplicación para una persona revisora autorizada. Si no hay uno configurado, mantén deshabilitada la acción dependiente y ofrece una derivación al equipo. No omitas la aprobación ni inventes una estructura de respuesta.

Comprobación de política completada (asistente de compras ficticio)
Política consultada: messages: true, conversations: true, files: false, artifacts: false.
Negociación: Se solicitaron runtime-standard-v1 y citas; la respuesta devuelve runtime-standard-v1 sin módulos de salida habilitados.
Interfaz: La aplicación muestra el compositor de conversación, oculta los controles para adjuntar archivos y consultar artefactos, y no presenta un panel de citas.
Resultado: La persona puede enviar una pregunta de texto; la interfaz no promete una función que la política no expone.

El ejemplo representa una respuesta de política ficticia, no la configuración predeterminada de AgentShelf. Una capacidad desactivada produce una denegación de esa capacidad, no datos vacíos. Trata ese estado como una función no disponible y compáralo con la política vigente en vez de repetir la misma solicitud.

Mantén vigentes las comprobaciones de política

Lee la política antes de mostrar controles y vuelve a consultarla cuando cambie el contexto operativo de la integración. No la conserves en caché más tiempo del que permite el ciclo de configuración del producto. Para las funciones que usan espacios de trabajo, comprueba también las capacidades habilitadas en la vinculación y el estado de preparación del runtime. Para diagnosticar fallos, consulta cómo solucionar problemas de integración con agentes externos; para configurar una sesión, lee cómo integrar un agente de AgentShelf.