Workspaces with an agent

Description and operation

General

An agent creates, starts, stops and deletes a workspace with the workspace tools of its session. A workspace that the agent creates is managed: the session deletes it when the session ends. For what a workspace is, see Workspaces.

Each tool except workspace_create and workspace_list takes workspace, the id of the workspace. The id starts with ws-; the name does not work. workspace_list shows the workspaces of the session with their ids. The agent changes files and processes with the tool server tools. It takes and restores snapshots as in Volumes with an agent.

Each lifecycle tool returns at once and the work continues. Poll workspace_get until state is ready, stopped, error or deleted.

Tasks

Create a workspace

Reason for the task: Get a new workspace to work in.

Job set-up

• Access: you. A team workspace needs team membership.
• Agent tool: workspace_create
• References: POST /v1/sessions/{id}/workspaces.

Procedure

1. Create the workspace in the session. name and quota_gb are required; add image or packages as needed.

   AI agentCopy

   {"tool": "workspace_create", "arguments": {"name": "backend", "quota_gb": 20}}

Close-out

1. Show the status as in task 002. Wait until state is ready.

The same task with the SDK or CLI: Create a workspace in a session.

Show the status of a workspace

Reason for the task: Check whether a workspace runs, and why not.

Job set-up

• Access: you.
• Agent tool: workspace_get
• References: GET /v1/workspaces/{id}.

Procedure

1. Show the workspace. The agent tool takes the id.

   AI agentCopy

   {"tool": "workspace_get", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b"}}

Close-out

1. Make sure that state is what you expect. If not, see Troubleshooting.

The same task with the SDK or CLI: Workspaces task 002.

Start a workspace

Reason for the task: Run a stopped workspace.

Job set-up

• Access: you.
• Agent tool: workspace_start
• References: POST /v1/workspaces/{id}/start.

Procedure

1. Start the workspace.

   AI agentCopy

   {"tool": "workspace_start", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b"}}

Close-out

1. Show the status as in task 002. Wait until state is ready.

The same task with the SDK or CLI: Workspaces task 003.

Stop a workspace

Reason for the task: Release the compute of a workspace and keep its home.

Job set-up

• Access: you.
• Agent tool: workspace_stop
• References: POST /v1/workspaces/{id}/stop.

Procedure

1. Stop the workspace.

   AI agentCopy

   {"tool": "workspace_stop", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b"}}

Close-out

1. Show the status as in task 002. Make sure that state is stopped.

The same task with the SDK or CLI: Workspaces task 004.

Delete a workspace

Reason for the task: Remove a workspace that you no longer need.

Job set-up

• Access: you.
• Agent tool: workspace_delete
• References: DELETE /v1/sessions/{id}/workspaces/{workspace}, Take a snapshot of a workspace.

Procedure

1. Delete the workspace.

   AI agentCopy

   {"tool": "workspace_delete", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b"}}

Close-out

1. Make sure that state is deleted.

The same task with the SDK or CLI: Delete a workspace in a session.

Add a package

Reason for the task: Install a tool in a workspace.

Job set-up

• Access: you.
• Agent tool: packages_add
• References: Find a package, PATCH /v1/workspaces/{id}, The kl command.

Procedure

1. Add the package, with @version to pin it. An entry with the same name replaces the old entry.

   AI agentCopy

   {"tool": "packages_add", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b", "packages": ["nodejs@22"]}}

Close-out

1. Show the packages as in task 007. Make sure that the entry and its lock are listed.

The same task with the SDK or CLI: Packages task 001.

Show the packages

Reason for the task: Check which tools and versions a workspace has.

Job set-up

• Access: you.
• Agent tool: packages_list
• References: GET /v1/workspaces/{id}.

Procedure

1. Show the packages and locks. Inside the workspace, kl pkg list does the same.

   AI agentCopy

   {"tool": "packages_list", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b"}}

Close-out

1. Make sure that every package that you expect is listed.

The same task with the SDK or CLI: Packages task 002.

Remove a package

Reason for the task: Remove a tool that you no longer need.

Job set-up

• Access: you.
• Agent tool: packages_remove
• References: PATCH /v1/workspaces/{id}.

Procedure

1. Remove the package by name, without a version. Inside the workspace, kl pkg rm jq does the same.

   AI agentCopy

   {"tool": "packages_remove", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b", "packages": ["jq"]}}

Close-out

1. Show the packages as in task 007. Make sure that the entry is gone.

The same task with the SDK or CLI: Packages task 003.

Update the locked versions

Reason for the task: Move each pinned package to the newest cached release that matches its version.

Job set-up

• Access: you.
• Agent tool: packages_update
• References: POST /v1/workspaces/{id}/packages/update.

Procedure

1. Run the update. Inside the workspace, kl pkg update does the same.

   AI agentCopy

   {"tool": "packages_update", "arguments": {"workspace": "ws-1a2b3c4d5e6f7a8b"}}

Close-out

1. Show the packages as in task 007. Make sure that the locks show the expected versions.

The same task with the SDK or CLI: Packages task 004.

Troubleshooting