Políticas y capacidades

Cada agente externo publica una política pública: qué puede hacer, qué perfiles de stream habla, qué contexto de host acepta y cuáles son sus límites. Léela antes de construir interfaz alrededor de una función — las capacidades son por agente, y llamar a una desactivada devuelve un error estable en lugar de degradarse en silencio.

Leer la política

const policy = await client.getEffectivePolicy();

if (policy.capabilities.files) {
  showAttachmentButton();
}

PublicExternalAgentPolicy:

Campo	Significado
capabilities	Booleanos para messages, conversations, files, artifacts, interactions, approvals.
streamProfiles / defaultStreamProfile	Perfiles que acepta el agente y el que se usa si no pides ninguno.
outputModuleTypes	Tipos de módulos de salida estructurada que el agente puede emitir.
providerGroundingDisplay	Si se puede mostrar al usuario el grounding del proveedor.
domainTools	Herramientas de dominio expuestas al agente, como PublicDomainTool.
filePolicy	upload, read, maxUploadBytes, allowedMimeTypes.
hostContextPolicy	acceptedFields y maxTotalBytes.
rateLimits / spendLimits	Se aplican en el servidor.
publicErrorDetail	minimal, standard o diagnostic — cuánto detalle llevan los errores públicos.
sdk.minVersion	Versión mínima del SDK que exige el agente, o null.

Negociar

prepare() propone una configuración y devuelve lo que el servidor realmente concedió. Lee siempre los valores negociados en lugar de asumir que tu petición se aceptó:

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

renderWith(negotiated.streamProfile, negotiated.outputModuleTypes);

negotiated informa del streamProfile, outputModuleTypes y providerGroundingDisplay resueltos. Tipo completo: ExternalAgentPrepareResult.

Perfiles de stream

Perfil	Uso
runtime-standard-v1	El stream público completo de eventos del runtime. Empieza aquí.
modules-v1	Módulos de salida estructurada.
chat-legacy-v1	Perfil de compatibilidad para integraciones de chat antiguas.

Herramientas de dominio

policy.domainTools describe las operaciones de dominio disponibles para el agente. Cada entrada incluye un publicName, un bloque operation (kind, sideEffectClass, idempotency, approvalRequired), esquemas opcionales de entrada y salida, y un status.

operation.approvalRequired es el que hay que contemplar en el diseño: esas herramientas emiten un evento approval:requested a mitad del stream y esperan. Ver Conversaciones y streaming.

Capacidades desactivadas

Llamar a una capacidad que la política ha desactivado falla con un error estable 403 unsupported_capability — no devuelve datos vacíos. Condiciona la interfaz a capabilities en lugar de usar el error como control de flujo.