Espacios de trabajo

Un binding de espacio de trabajo es un asiento de runtime para la terna aplicación externa × agente externo × usuario externo actual. Es lo que respalda las capacidades que necesitan estado duradero: una biblioteca de contexto con archivos, scripts, un contenedor.

ensureWorkspace() es opcional. Las integraciones de solo chat nunca lo necesitan.

Materializar un binding

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

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

clientWorkspaceKey es una clave de idempotencia. Reutiliza el mismo valor para el mismo asiento lógico y recibirás el mismo binding con created: false, en lugar de acumular asientos.

EnsureWorkspaceResult devuelve workspaceBindingRef, un workspaceRef opcional, status, created, capabilitiesEnabled y policy. Ten en cuenta que capabilitiesEnabled es lo que realmente se te concedió: puede ser más restrictivo que requestedCapabilities.

La llamada es lógica de cliente HTTP sin interfaz y devuelve solo refs públicas. Los IDs internos de workspace, runtime y almacenamiento, los nombres de bucket y los IDs de tool binding de AgentShelf nunca forman parte de la respuesta.

Esperar al runtime

Un binding puede existir antes de que su runtime esté listo. Dos métodos cubren esto:

const status = await client.getWorkspaceRuntimeStatus();

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

WorkspaceRuntimeStatus informa de lifecycleState, status y los booleanos sobre los que conviene ramificar — ready, provisioning, failed, canRunScripts, hasContainer — más un statusMessage opcional que puedes mostrar mientras el usuario espera.

Ambos aceptan un AbortSignal, así que un usuario que navega fuera puede cancelar el sondeo:

const controller = new AbortController();
await client.waitForWorkspaceRuntime({ signal: controller.signal });

waitForWorkspaceRuntime rechaza con el código de error timeout si el runtime no está listo a tiempo, y con aborted si se dispara la señal. Trata failed: true como terminal: volver a sondear no lo recuperará.

Cuándo necesitas uno

Escenario	¿Espacio de trabajo?
Chat, streaming, artefactos	No
Operaciones de archivos en la biblioteca de contexto	Sí
Cualquier cosa que requiera canRunScripts	Sí

Las operaciones de archivos sobre la biblioteca de contexto requieren un binding materializado y soporte en la política — ver Archivos y artefactos.