Agentic workflows – Volumes

Description and operation

General

An agent saves and recovers work with the snapshot, clone and restore tools. The platform chapter Volumes explains the volume, its lineage and its snapshots. This page gives the tool call for each task.

Four rules are specific to an agent:

• The history, refs and delete tools take the id of a volume, never its name. Read the id from volume_list, or from the volume field of the workspace or the environment.
• The first push of a volume must give volume, its name. Each later push is a version. Restore and clone take snapshot_id as a reference: name, name@N or a snapshot id. See Names and versions.
• A push, a clone and a restore return 202 at once. The agent polls the phase in the history, or the state of the new workspace or environment.
• When env_restore answers 409 with lost, the agent names the services in discard only after the developer accepts the loss.

An agent clones to try a change on a copy, and deletes the copy when it is done.

Tasks

Take a snapshot of a workspace

Reason for the task: Save the state of a workspace in a snapshot.

Job set-up

• Access: you
• Agent tool: workspace_snapshot
• References: POST /v1/workspaces/{id}/snapshots

Procedure

1. Push a snapshot with a note in message. Add the volume name in volume for the first push.

   AI agentCopy

   {"tool": "workspace_snapshot", "arguments": {"workspace": "ws-0a1b2c3d4e5f6a7b", "message": "before the refactor", "volume": "backend-base"}}

Close-out

1. Show the history, as in task 003. Wait until the first row shows your note and the phase ready.

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

Take a snapshot of an environment

Reason for the task: Save the services and the data of an environment in a snapshot.

Job set-up

• Access: you
• Agent tool: env_snapshot
• References: POST /v1/environments/{id}/snapshots

Procedure

1. Push a snapshot with a note in message. Add the volume name in volume for the first push.

   AI agentCopy

   {"tool": "env_snapshot", "arguments": {"env": "env-1f2e3d4c5b6a7988", "message": "before the schema change", "volume": "dev-data"}}

Close-out

1. Show the history, as in task 003. Wait until the first row shows your note and the phase ready.

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

Show the snapshot history

Reason for the task: Find the snapshots of a workspace or an environment and their ids.

Job set-up

• Access: you
• Agent tool: volume_history
• Conditions: you know the id of the volume, which is the id of the workspace or the environment. See Show the volumes.
• References: GET /v1/volumes/{key}/history, GET /v1/volumes/{key}/refs

Procedure

1. Show the lineage, tip first.

   AI agentCopy

   {"tool": "volume_history", "arguments": {"volume": "ws-0a1b2c3d4e5f6a7b"}}

2. Show the tip, main. A clone or a restore uses it by default.

   AI agentCopy

   {"tool": "volume_refs", "arguments": {"volume": "ws-0a1b2c3d4e5f6a7b"}}

Close-out

1. Write down the id of the snapshot for a restore, a clone or a delete.

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

Delete a snapshot

Reason for the task: Remove a snapshot that you do not need.

Job set-up

• Access: you
• Agent tool: snapshot_delete
• Conditions: no running workspace or environment is based on the snapshot.
• References: DELETE /v1/volumes/{key}/snapshots/{snapshot}

Procedure

1. Delete the snapshot. Use the id from the history for snapshot.

   AI agentCopy

   {"tool": "snapshot_delete", "arguments": {"volume": "ws-0a1b2c3d4e5f6a7b", "snapshot": "ws-0a1b2c3d4e5f6a7b-8a7b6c91"}}

Close-out

1. Show the history. The id is gone, or the call returns 404 if the volume went with it.

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

Clone a workspace

Reason for the task: Make a new workspace that starts with a copy of the files of a workspace.

Job set-up

• Access: you
• Agent tool: workspace_clone
• References: POST /v1/workspaces/{id}/clone

Procedure

1. Clone the workspace. Use a free name for name.

   AI agentCopy

   {"tool": "workspace_clone", "arguments": {"workspace": "ws-0a1b2c3d4e5f6a7b", "name": "api-experiment", "task": "try the new parser"}}

Close-out

1. Make sure that interrupted is false, then wait until the new workspace is ready.

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

Clone an environment

Reason for the task: Make a new environment from the present state of an environment, or from one of its snapshots.

Job set-up

• Access: you
• Agent tool: env_clone
• References: POST /v1/environments/{id}/clone

Procedure

1. Clone the present state of the environment. Use a plain name for name.

   AI agentCopy

   {"tool": "env_clone", "arguments": {"env": "env-1f2e3d4c5b6a7988", "name": "dev-copy"}}

2. Give the id of a snapshot in snapshot_id to clone that snapshot. See Show the snapshot history.

   AI agentCopy

   {"tool": "env_clone", "arguments": {"env": "env-1f2e3d4c5b6a7988", "name": "dev-before-migration", "snapshot_id": "env-1f2e3d4c5b6a7988-8a7b6c91"}}

Close-out

1. Wait until the state of the new environment is running, then check its services.

The same task with the SDK or CLI: Environments task 008.

Restore a workspace from a snapshot

Reason for the task: Make a new workspace from the state that a snapshot froze.

Job set-up

• Access: you
• Agent tool: workspace_restore
• Conditions: you know the id of a ready snapshot of a workspace. See Show the snapshot history.
• References: POST /v1/workspaces/restore

Procedure

1. Restore the workspace. Use the id for snapshot_id, and a free name for name.

   AI agentCopy

   {"tool": "workspace_restore", "arguments": {"name": "api-restored", "snapshot_id": "ws-0a1b2c3d4e5f6a7b-8a7b6c91"}}

2. Add image, packages or quota_gb to the same call to override a value.

   AI agentCopy

   {"tool": "workspace_restore", "arguments": {"name": "api-restored", "snapshot_id": "ws-0a1b2c3d4e5f6a7b-8a7b6c91", "quota_gb": 40}}

Close-out

1. Wait until the new workspace is ready, then check its packages.

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

Restore an environment from a snapshot

Reason for the task: Put an environment back to the services and the data of one of its snapshots.

Job set-up

• Access: you
• Agent tool: env_restore
• Conditions: you know the id of a ready snapshot of this environment. No service that the restore removes has an intercept.
• References: POST /v1/environments/{id}/restore, Remove an intercept

Procedure

1. Restore the environment. Use the id of the snapshot for snapshot_id.

   AI agentCopy

   {"tool": "env_restore", "arguments": {"env": "env-1f2e3d4c5b6a7988", "snapshot_id": "env-1f2e3d4c5b6a7988-8a7b6c91"}}

2. If the call returns 409 with a list lost, restore again and name those services in discard.

   AI agentCopy

   {"tool": "env_restore", "arguments": {"env": "env-1f2e3d4c5b6a7988", "snapshot_id": "env-1f2e3d4c5b6a7988-8a7b6c91", "discard": ["redis"]}}

Close-out

1. Read rolled_back, added, removed and discarded in the answer. Wait until the state is running.

The same task with the SDK or CLI: Environments task 009.

Show the volumes

Reason for the task: Find the volumes that hold your snapshots, and which of them nothing uses.

Job set-up

• Access: you
• Agent tool: volume_list
• References: GET /v1/volumes

Procedure

1. Show the volumes. Use kind and owner to filter the list.

   AI agentCopy

   {"tool": "volume_list", "arguments": {"kind": "environment", "owner": "acme"}}

Close-out

1. Write down the id of the volume. Where deleted is true, nothing uses it.

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

Delete a volume

Reason for the task: Remove a detached volume and all its snapshots to free disk.

Job set-up

• Access: you
• Agent tool: volume_delete
• Conditions: deleted is true. See Show the volumes.
• References: DELETE /v1/volumes/{key}

Procedure

1. Delete the volume. Use its id.

   AI agentCopy

   {"tool": "volume_delete", "arguments": {"volume": "env-1f2e3d4c5b6a7988"}}

Close-out

1. Show the volumes. The deleted name is gone.

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

Troubleshooting