Agentic workflows – General
Let an AI agent operate your session, workspaces and environments through the Kloudlite tools.
Last updated
On this page
Description and operation
General
An AI agent works in a session. The session gives the agent its tools: one tool for each action on the session, its workspaces and its environment. An agent acts with the account, rights and limits of the developer it works for. A quota or a paused team access that stops you also stops your agent. See Limits.
This chapter covers only what is specific to an agent: how it connects, which tool does a job, and the exact call. Each page names the page of the platform chapter that explains the subject.
Three ways connect an agent to the tools. Each way is one page.
| Way | Where the agent runs | What the agent gets |
|---|---|---|
| Claude Code | On your laptop | The tools of your session, and no access to the laptop. |
| MCP | In any client that speaks MCP | The same tools, from kloudlite mcp. |
| The Kloudlite harness | In kl-tui, the harness that kloudlite opens | The same tools, in a session that you open. |
The other pages describe the tools by subject.
| Page | Subject |
|---|---|
| Workspaces | Create, start, stop and delete a workspace, and change its packages. |
| Environments | Create an environment, change its services, and intercept a service. |
| Volumes | Take a snapshot, clone, restore, and delete snapshots and volumes. |
| Tool server | Read and run in one workspace over plain HTTP, from a program. |
The kl command | Manage packages, read the session environment and build an image from inside a workspace. |
Tools
Each tool takes the workspace or the environment that it acts on, as an id. A workspace id starts with ws- and an environment id with env-. A name does not work. A tool that starts work returns 202 at once, and the agent polls the matching *_get tool or calls env_wait. See Agent tools for the arguments and the route of each tool.
| Area | Acts on | Tools |
|---|---|---|
| Session | The session itself | session_current, session_use, session_pick, session_connect, session_disconnect |
| Workspace lifecycle | The workspaces of the session | workspace_list, workspace_get, workspace_create, workspace_start, workspace_stop, workspace_delete, workspace_ask |
| Workspace code | A workspace of the session | read, write, edit, patch, glob, grep, exec, process_*, watch*, worktree_add, worktree_drop |
| Packages and images | A workspace and its builder | packages_list, packages_add, packages_remove, packages_update, container_build, container_push, builder_status |
| Environment | An environment | env_list, env_get, env_wait, env_create, env_start, env_stop, env_delete, service_add, service_update, service_remove, service_logs, intercept, release |
| Volumes | A volume | workspace_snapshot, env_snapshot, workspace_clone, env_clone, workspace_restore, env_restore, volume_list, volume_history, volume_refs, volume_delete, snapshot_delete |
| Account | The quota and the requests of an owner | quota, regions, request_create, request_get, requests_list |
| Web | The internet | web_fetch, web_search |
| Work of the agent | The board and the scratch folder of the session | task_add, task_update, task_list, workspace_tasks, scratch_bash, scratch_read, scratch_write |
The account tools call the routes that the tasks of Quota and requests and Regions describe.
Scopes
An agent does not hold every tool. The tools it holds depend on where it runs. Three scopes exist: the platform, the session and one workspace.
| Scope | Held by | Tools |
|---|---|---|
| Platform | Every agent that reaches the API | The account tools, the volume tools and web_fetch, web_search. They act on an owner or a volume, not on one workspace. |
| Session | Claude Code, an MCP client and the main session of the harness | The session, workspace lifecycle, environment, volume and account tools, with the board and the scratch folder. The main session has no code tools. |
| Workspace | The session of one workspace | The code tools and the packages, container and environment tools of its own workspace. They take no workspace argument. It also has main_tell and subagent. |
Claude Code and an MCP client serve the tools of all three scopes in one list. Each tool then takes the workspace or env that it acts on. The harness splits them, so that a main session directs and a workspace session works:
- The main session creates, starts, stops and deletes workspaces and environments. It holds
packages_listbut notpackages_add,packages_removeorpackages_update. It cannotinterceptorreleasea service. - The session of a workspace holds the code tools,
packages_add,packages_remove,packages_update,intercept,release,service_*andworkspace_stop. It reports to the main session withmain_tell. - A subagent runs in a clone of a workspace. It holds the tools of that workspace without
workspace_stop,intercept,release, the board,workspace_ask,main_tellandsubagent.
workspace_create and workspace_delete act through the session. A workspace that an agent creates belongs to the session, and the agent deletes it through the same session.