Environments and intercepts with an agent

Description and operation

General

An agent runs an environment with the environment tools. For what an environment is, see Environments. Each tool except env_create and env_list takes env, the id of the environment. The id starts with env-; the name does not work. env_list shows the environments of a team with their ids.

Each change tool returns at once. env_wait waits until every service is ready, a service is failing, or state is error or deleted. It takes timeout in seconds (default 300, maximum 900) and returns timedOut: true if the wait ends first. A service with failing: true does not come up by waiting: read its message, fix the cause and change the service again.

A session connects to one environment of its own team, and a workspace of the session reaches its services by name. The agent connects it with session_connect and takes the traffic of a service with intercept. See Sessions and Intercepts.

service_logs reads the recent output of one service. It takes service, tail (default 200, maximum 2000), since (seconds, maximum 86400) and previous (the run before a crash). It starts an idle-stopped environment first. If an intercept holds the service, the answer names the workspace that serves it.

Tasks

Create an environment

Reason for the task: Run the services of an application for workspaces to develop against.

Job set-up

• Access: you. A team environment needs team membership.
• Agent tool: env_create
• References: POST /v1/environments, Services.

Procedure

1. Create the environment with its services. Give snapshot_id instead to grow it from a snapshot.

   AI agentCopy

   {"tool": "env_create", "arguments": {"name": "acme-dev", "services": [{"name": "db", "image": "postgres:16", "ports": [5432], "env": {"POSTGRES_PASSWORD": "dev"}, "mounts": [{"folder": "pgdata", "path": "/var/lib/postgresql/data"}]}], "quota_gb": 20}}

Close-out

1. Wait with env_wait. Make sure that state is running and every service is ready.

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

Show the status of an environment

Reason for the task: Check whether an environment and its services run, and why not.

Job set-up

• Access: you. A team environment needs team membership.
• Agent tool: env_get
• References: GET /v1/environments/{id}, GET /v1/environments.

Procedure

1. Show the environment. Each entry of services has ready; env_list shows all environments of a team.

   AI agentCopy

   {"tool": "env_get", "arguments": {"env": "env-1f2e3d4c5b6a7988"}}

Close-out

1. Make sure that state and the ready value of each service are what you expect. If not, see Troubleshooting.

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

Start an environment

Reason for the task: Run a stopped environment.

Job set-up

• Access: you. A team environment needs team membership.
• Agent tool: env_start
• References: POST /v1/environments/{id}/start.

Procedure

1. Start the environment.

   AI agentCopy

   {"tool": "env_start", "arguments": {"env": "env-1f2e3d4c5b6a7988"}}

Close-out

1. Wait with env_wait. Make sure that state is running and every service is ready.

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

Stop an environment

Reason for the task: Release the compute of an environment and keep its data.

Job set-up

• Access: you. A team environment needs team membership.
• Agent tool: env_stop
• References: POST /v1/environments/{id}/stop.

Procedure

1. Stop the environment.

   AI agentCopy

   {"tool": "env_stop", "arguments": {"env": "env-1f2e3d4c5b6a7988"}}

Close-out

1. Make sure that state is stopped. A warning in the response means that the machine of the environment is down.

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

Delete an environment

Reason for the task: Remove an environment that you no longer need.

Job set-up

• Access: you. A team environment needs team membership.
• Agent tool: env_delete
• References: DELETE /v1/environments/{id}, Volumes.

Procedure

1. Delete the environment.

   AI agentCopy

   {"tool": "env_delete", "arguments": {"env": "env-1f2e3d4c5b6a7988"}}

Close-out

1. Make sure that the environment is no longer listed. A warning in the response names a session that was not disconnected.

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

Add a service

Reason for the task: Run another program in an environment.

Job set-up

• Access: you. A team environment needs team membership.
• Agent tool: service_add
• References: PATCH /v1/environments/{id}.

Procedure

1. Add the service.

   AI agentCopy

   {"tool": "service_add", "arguments": {"env": "env-1f2e3d4c5b6a7988", "service": {"name": "cache", "image": "redis:7", "ports": [6379]}}}

Close-out

1. Wait with env_wait. Make sure that cache is ready.

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

Change a service

Reason for the task: Change the image, variables, ports or mounts of a service.

Job set-up

• Access: you. A team environment needs team membership.
• Agent tool: service_update
• References: PATCH /v1/environments/{id}.

Procedure

1. Send the changed service, here db on postgres:17. The agent tool replaces the whole service, so give every field.

   AI agentCopy

   {"tool": "service_update", "arguments": {"env": "env-1f2e3d4c5b6a7988", "service": {"name": "db", "image": "postgres:17", "ports": [5432], "env": {"POSTGRES_PASSWORD": "dev"}, "mounts": [{"folder": "pgdata", "path": "/var/lib/postgresql/data"}]}}}

Close-out

1. Wait with env_wait. Make sure that the service shows the new value and is ready.

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

Remove a service

Reason for the task: Stop a program and take it out of an environment.

Job set-up

• Access: you. A team environment needs team membership.
• Agent tool: service_remove
• References: PATCH /v1/environments/{id}.

Procedure

1. Remove the service by name. Its folders stay on the disk.

   AI agentCopy

   {"tool": "service_remove", "arguments": {"env": "env-1f2e3d4c5b6a7988", "name": "cache"}}

Close-out

1. Make sure that the service is no longer in services.

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

Read the logs of a service

Reason for the task: See what a service wrote, for example before it failed.

Job set-up

• Access: you. A team environment needs team membership.
• Agent tool: service_logs
• References: Services.

Procedure

1. Read the last 200 lines. Add "previous": true to read the run before a crash.

   AI agentCopy

   {"tool": "service_logs", "arguments": {"env": "env-1f2e3d4c5b6a7988", "service": "db", "tail": 200}}

Close-out

1. Make sure that the lines come from the service that you named.

Connect an environment to a session

Reason for the task: Give the workspaces of the session the services of an environment.

Job set-up

• Access: you.
• Agent tool: session_connect
• Conditions: the environment belongs to the team of the session.
• References: PUT /v1/sessions/{id}/environment, kloudlite sessions connect-env.

Procedure

1. Connect the environment by name or id. The tool acts on the session that the agent serves.

   AI agentCopy

   {"tool": "session_connect", "arguments": {"environment": "shop"}}

Close-out

1. Show the session with session_current. Make sure that environment shows the environment.

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

Change or disconnect the environment

Reason for the task: Move a session to another environment, or detach it.

Job set-up

• Access: you.
• Agent tool: session_disconnect
• References: PUT /v1/sessions/{id}/environment, kloudlite sessions disconnect-env.

Procedure

1. Set the session to no environment.

   AI agentCopy

   {"tool": "session_disconnect", "arguments": {}}

2. Connect the new environment as in task 010 to change it.

Close-out

1. Show the session with session_current. Make sure that environment shows the new id, or no value after a disconnect.

The same task with the SDK or CLI: Sessions task 005.

Intercept a service

Reason for the task: Run a service from your workspace against the rest of the environment.

Job set-up

• Access: you.
• Agent tool: intercept
• Conditions: the session is connected to the environment. The workspace is in the session and runs. The service declares a port.
• References: POST /v1/environments/{id}/intercepts.

Procedure

1. Create the intercept. Map ports with ports: this example sends 8080 to 3000.

   AI agentCopy

   {"tool": "intercept", "arguments": {"env": "env-1a2b3c4d5e6f7a8b", "service": "api", "workspace": "ws-1a2b3c4d5e6f7a8b", "ports": [{"service": 8080, "workspace": 3000}]}}

Close-out

1. Get the environment with env_get. Make sure that the service in service_status shows interceptedBy and that proxy is ready.

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

Show the intercepts

Reason for the task: Check which services your session routes to a workspace.

Job set-up

• Access: you.
• Agent tool: env_get
• References: GET /v1/environments/{id}.

Procedure

1. Show the environment. The answer lists every intercept of the environment, with its session.

   AI agentCopy

   {"tool": "env_get", "arguments": {"env": "env-1a2b3c4d5e6f7a8b"}}

Close-out

1. Make sure that every service that you intercepted is listed.

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

Remove an intercept

Reason for the task: Give a service its traffic back.

Job set-up

• Access: you.
• Agent tool: release
• References: DELETE /v1/environments/{id}/intercepts/{service}.

Procedure

1. Remove the intercept.

   AI agentCopy

   {"tool": "release", "arguments": {"env": "env-1a2b3c4d5e6f7a8b", "service": "api"}}

Close-out

1. Show the intercepts as in task 013. Make sure that the service is gone.

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

Troubleshooting