Decide cuándo un agente externo necesita un espacio de trabajo

Un agente externo puede usar un espacio de trabajo opcional para funciones que necesitan estado duradero, como archivos de una biblioteca de contexto o scripts. Una integración que solo usa chat no lo necesita. Si solicitas un espacio de trabajo, usa una clave estable, comprueba qué capacidades se habilitaron y espera a que el entorno de ejecución esté listo antes de mostrar las acciones que dependen de él.

El diagrama muestra el navegador, el servidor, el agente, el resultado y los límites de sesión y error; los flujos que necesitan estado duradero también deben comprobar que el entorno esté listo.

Decide si la función necesita estado duradero

Empieza por la tarea que verá el usuario, en vez de aprovisionar un espacio de trabajo por defecto. La mensajería, el historial de conversaciones y los artefactos pueden usar la sesión pública sin ensureWorkspace(). Las operaciones con archivos de la biblioteca de contexto y las funciones que requieren ejecutar scripts dependen de un binding de espacio de trabajo materializado y del soporte de la política.

Desplázate horizontalmente para ver todas las columnas.

La política pública sigue formando parte de la decisión. La respuesta del espacio de trabajo incluye capabilitiesEnabled, que puede ser más limitada que requestedCapabilities; que exista un binding no demuestra que estén disponibles todas las operaciones solicitadas.

Materializa un asiento lógico de espacio de trabajo

El cliente documentado acepta las capacidades solicitadas y un clientWorkspaceKey:

const workspace = await client.ensureWorkspace({
  requestedCapabilities: ['files'],
  clientWorkspaceKey: 'checkout-support-seat',
});

console.log(workspace.workspaceBindingRef, workspace.capabilitiesEnabled);

Elige la clave para el asiento lógico que representa la integración y reutilízala para ese mismo asiento. La clave es idempotente: una solicitud repetida devuelve el mismo binding en vez de acumular otro. No generes una nueva clave aleatoria en cada carga de página. Trata la referencia pública del espacio de trabajo como una referencia; no sustituye la identidad de sesión ni una comprobación de autorización.

Espera a que el entorno esté listo

Un binding puede existir mientras su entorno de ejecución todavía se aprovisiona. Evalúa los indicadores de estado en lugar de suponer que una respuesta de binding correcta demuestra que ya se puede empezar el trabajo:

const status = await client.getWorkspaceRuntimeStatus();

if (!status.ready) {
  await client.waitForWorkspaceRuntime({
    timeoutMs: 60_000,
    pollIntervalMs: 2_000,
  });
}

El estado incluye ready, provisioning, failed, canRunScripts y hasContainer, además de campos del ciclo de vida y estado. Muestra una espera útil mientras se aprovisiona el entorno. Un vencimiento de tiempo significa que no estuvo listo dentro del período solicitado; una espera cancelada significa que quien llamó la función la canceló. Trata failed: true como estado terminal en vez de sondearlo indefinidamente. Para cancelar una espera, pasa una señal AbortSignal, tal como se explica en la guía de espacios de trabajo.

Comprobación de configuración completada (portal de soporte ficticio)

Solicitud: El portal necesita una biblioteca de contexto persistente para el agente de soporte; el chat habitual funciona sin ella.

Espacio de trabajo: ensureWorkspace() recibe requestedCapabilities: ['files'] y la clave estable support:employee-42.

Permiso: La respuesta incluye una workspaceBindingRef pública y capabilitiesEnabled: ['files'].

Disponibilidad: El estado del entorno de ejecución indica ready: true; la aplicación habilita la acción de la biblioteca de contexto después de comprobar también el soporte de la política.

Repetición: Al volver a usar support:employee-42, se devuelve el mismo binding con created: false.

Este ejemplo distingue tres hechos: la aplicación solicitó un binding, el servidor informó qué capacidad habilitó y el entorno de ejecución indicó si estaba listo. Si falta cualquiera de esas comprobaciones, mantén deshabilitada la función dependiente. La API del espacio de trabajo expone referencias públicas, no IDs internos de espacios de trabajo ni ubicaciones de almacenamiento.

Comprueba todos los límites

Antes del lanzamiento, confirma que la tarea realmente requiere estado duradero, que la clave solicitada siga siendo estable para el asiento previsto, que las capacidades habilitadas satisfagan la tarea y que la preparación se compruebe antes del uso. Después, prueba una solicitud repetida y una ruta donde el entorno no esté disponible. Para la identidad de sesión y los tokens almacenados, consulta referencias públicas e inicialización segura; para archivos que se pasan en una conversación, consulta sesiones, conversaciones y artefactos.