Workspaces

client.workspaces manages workspaces: private file systems that keep your agents' files between sessions. Several agents in your tenant can share one workspace, and its network policy controls what those agents can reach from it.

Every agent gets its own workspace when you create it, so you only need this resource to share a workspace, restrict its network, or clean up. Creating a workspace costs nothing until an agent first uses its files.

Examples assume client = BlazingAgents(). Every method also accepts extra_headers and timeout. On AsyncBlazingAgents, await the same method names and use async for with iter().

workspace = client.workspaces.create(
    name="Release files",
    network_policy={"mode": "allowlist", "allowed_hosts": ["registry.npmjs.org"]},
)
agent = client.agents.update("ag_0123456789abcdef", workspace_id=workspace.id)

Available operations

Methods

create()

Creates an empty workspace.

workspace = client.workspaces.create(
    name="Customer files",
    user_id="customer_123",
    metadata={"project": "docs"},
)

Signature: create(*, name=..., user_id=..., metadata=..., network_policy=...) -> Workspace

A network policy is one of {"mode": "unrestricted"}, {"mode": "offline"}, or {"mode": "allowlist", "allowed_hosts": [...]}.

Returns Workspace. Raises APIStatusError with validation_failed.

list()

Gets one page of workspaces, newest first.

page = client.workspaces.list(user_id="customer_123", limit=50)
if page.next_cursor is not None:
    page = client.workspaces.list(cursor=page.next_cursor, limit=50)

Signature: list(*, cursor=..., limit=..., user_id=...) -> WorkspacesPage

limit is 1 to 200 and defaults to 50. Pass the previous page's next_cursor as cursor. user_id="" returns tenant-level workspaces; omitting user_id returns all of them.

Returns WorkspacesPage with data: list[Workspace] and next_cursor: str | None. Raises validation_failed or invalid_cursor.

iter()

Iterates every workspace, fetching pages as you go.

for workspace in client.workspaces.iter(user_id="customer_123"):
    print(workspace.id, workspace.name)

Signature: iter(*, cursor=..., limit=..., user_id=...) -> Iterator[Workspace]

Takes the same parameters as list(). No request is sent until you start iterating. On the async client, use async for directly on iter(...); do not await it.

get()

Gets one workspace.

workspace = client.workspaces.get(workspace_id="ws_0123456789abcdef")

Signature: get(*, workspace_id: str) -> Workspace

Returns Workspace. Raises validation_failed or workspace_not_found.

update()

Changes a workspace's name, metadata, or network policy.

workspace = client.workspaces.update(
    workspace_id=workspace.id,
    name=None,
    network_policy={"mode": "offline"},
)

Signature: update(*, workspace_id: str, name=..., metadata=..., network_policy=...) -> Workspace

Omitted parameters keep their current value. name=None clears the name. metadata and network_policy replace the current values completely. user_id cannot change. Calling update() with nothing to change raises ValueError before any request.

Returns Workspace. Raises validation_failed or workspace_not_found.

delete()

Deletes a workspace and all its files.

outcome = client.workspaces.delete(workspace_id=workspace.id)

Signature: delete(*, workspace_id: str) -> WorkspaceDeletionOutcome

Move every agent to another workspace first. Returns "completed" when deletion finished right away, or "pending" when it was accepted and cleanup continues in the background.

Response types

Workspace

Next

• Workspaces guide
• Built-in tools
• Agents