Decide When an External Agent Needs a Workspace

An external agent can use an optional workspace for capabilities that need durable state, such as context-library files or scripts. A chat-only integration does not need one. If you request a workspace, use a stable key, check which capabilities were enabled, and wait for the runtime to be ready before showing actions that depend on it.

The diagram shows the browser, server, agent, result, session, and error path; workspace readiness is an additional runtime check for integrations that need durable state.

Decide whether the feature needs durable state

Start from the user-visible task rather than provisioning a workspace by default. Messaging, conversation history, and artifacts can use the public session without ensureWorkspace(). Context-library file operations and features that require script execution depend on a materialized workspace binding and policy support.

Scroll horizontally to see all columns.

The public policy remains part of the decision. A workspace response reports capabilitiesEnabled, which can be narrower than requestedCapabilities; the existence of a binding does not prove that every requested operation is available.

Materialize one logical workspace seat

The documented client accepts requested capabilities and a clientWorkspaceKey:

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

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

Choose the key for the logical seat represented by your integration, then reuse it for that same seat. The key is idempotent: a repeated request returns the same binding rather than accumulating another one. Do not generate a new random key for every page load. Keep the public workspace reference as a reference; it is not a replacement for session identity or an authorization check.

Wait for runtime readiness

A binding can exist while its runtime is still provisioning. Branch on the status booleans rather than treating a successful binding response as proof that work can start:

const status = await client.getWorkspaceRuntimeStatus();

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

The status includes ready, provisioning, failed, canRunScripts, and hasContainer, along with lifecycle and status fields. Surface a useful waiting state while provisioning. A timeout means the runtime did not become ready within the requested wait; an aborted wait means the caller cancelled it. Treat failed: true as terminal instead of polling indefinitely. For cancellable waits, pass an AbortSignal as described in the workspace guide.

Completed setup check (fictional support portal)
Request: The portal needs a persistent context library for the support agent; ordinary chat works without it.
Workspace: ensureWorkspace() receives requestedCapabilities: ['files'] and the stable key support:employee-42.
Grant: The response includes a public workspaceBindingRef and capabilitiesEnabled: ['files'].
Readiness: The runtime status reports ready: true; the app enables the context-library action after also checking policy support.
Repeat: Reusing support:employee-42 returns the same binding with created: false.

This example separates three facts: the app requested a binding, the server reported the enabled capability, and the runtime reported readiness. If any one of those checks is missing, keep the dependent feature unavailable. The workspace API exposes public refs, not raw internal workspace IDs or storage locations.

Verify the full boundary

Before rollout, confirm that the job actually requires durable state, the requested key remains stable for the intended seat, enabled capabilities satisfy the job, and readiness is checked before use. Then test a repeated request and an unavailable runtime path. For session identity and stored tokens, read public references and secure bootstrap; for files passed into a conversation, see sessions, conversations, and artifacts.