Operate ECS instances by using Workbench CLI in AI agents - Elastic Compute Service

Load the Workbench CLI skill into AI coding tools such as Wukong, Qoder, and opencode, and use natural language to drive an agent to query ECS instances, run commands, and transfer files. With structured JSON output and command exit code passthrough, the agent can independently evaluate results and chain subsequent operations.

Why AI Agents Are Well Suited to Workbench CLI

Compared with other ways to connect to ECS instances, Workbench CLI is inherently suited to being called by AI agents:

Structured JSON output: All commands support --output json and return a predictable field structure (for example, exec returns output, stderr, and exit_code), so the agent does not need to parse text output with regular expressions.
Exit code passthrough: workbench exec passes through the exit code of the remote command (consistent with SSH), so the agent can determine whether the remote command succeeded. When a command fails, --output json outputs structured error information, which the agent can parse to decide whether to retry or report an error.
Stateless execution: Each call to workbench exec runs in an independent environment with no shell state carried over. The agent does not need to maintain session context, and command behavior is not made unpredictable by leftover state.
Intuitive command semantics: The names list / exec / upload / download map one-to-one to common operations tasks, so the agent can learn to use them on its own through --help.

Prerequisites

Workbench CLI is installed on your computer, and credentials and a least-privilege RAM policy are configured. For more information, see Install Workbench CLI and configure credentials.
The target AI coding tool (Wukong, opencode, or another AI tool that can run shell commands) is installed on your computer.
We recommend that you first read Manage ECS instances by using Workbench CLI to familiarize yourself with the usage of each workbench subcommand, so that you can better evaluate the agent's output.

Load the Workbench CLI Skill into an AI Tool

Alibaba Cloud has released an official Workbench CLI skill that includes the usage of all subcommands, parameter descriptions, exit code meanings, and typical workflows. After the skill is loaded into an AI coding tool, the agent can independently call the workbench command when you express your operations intent in natural language. The following sections describe how to load the skill in Qoder, Wukong, and opencode, in that order.

Qoder

In the terminal where Qoder runs, run the following command to load the official skill with the skills CLI.

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-workbench-cli --agent qoder -y --full-depth

After the skill is loaded, you can try the following conversation in Qoder to verify it:

You: Deploy the local app.jar to the /opt/app directory on instance i-bp1a2b3c4d5e6f.
Agent: (Calls workbench upload and then workbench exec to complete the deployment, and reports the result step by step.)

Wukong

Wukong does not yet support one-command loading with the skills CLI. You need to download the skill package and import it manually:

Go to the Workbench CLI Skill page and download the skill ZIP package.
Import the downloaded ZIP package into Wukong.
Enable (load) the skill after the import.

After the skill is loaded, you can try the following conversation in Wukong to verify it:

You: Use workbench to list the running instances in China (Hangzhou).
Agent: (Automatically runs workbench list ecs -r cn-hangzhou --status Running --output json and summarizes the result.)

opencode

In the terminal where opencode runs, run the following command to load the official skill with the skills CLI.

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-workbench-cli --agent opencode -y --full-depth

After the skill is loaded, you can try the following conversation in opencode to verify it:

You: Connect to instance i-bp1a2b3c4d5e6f and check its disk usage.
Agent: (Automatically runs workbench exec -i i-bp1a2b3c4d5e6f -c "df -h" --output json and explains the result.)

For more AI tools, visit the Workbench CLI Skill page.

General Method: Let the Agent Learn from --help

If your AI tool does not support the official Alibaba Cloud skill, or if you want a quick way to verify it, you can have the agent learn on its own by reading the --help output. This works with any agent that can run shell commands.

Read the output of workbench --help and learn to use the workbench tool to manage and operate my Alibaba Cloud ECS instances.

The agent automatically runs workbench --help and workbench <subcommand> --help to understand the usage of all subcommands layer by layer, and then uses --output json to obtain structured results for subsequent processing.

Note

Compared with explicitly loading the skill, the general method requires the agent to re-read the help output in each new session, consumes more context, and lacks the best practices and error-handling guidance built into the skill. For long-term use, we recommend that you load the skill explicitly.

Typical Conversation Scenarios

Scenario 1: Query Running Instances

User prompt:

List the running instances in China (Hangzhou).

Agent execution:

workbench list ecs -r cn-hangzhou --status Running --output json

Simplified response:

{
  "instances": [
    { "instance_id": "i-bp1a2b3c...", "instance_name": "web-prod-01", "status": "Running", "private_ip": "172.16.0.10" },
    { "instance_id": "i-bp2x4y5z...", "instance_name": "api-prod-02", "status": "Running", "private_ip": "172.16.0.11" }
  ]
}

Agent summary: China (Hangzhou) (cn-hangzhou) currently has 2 running instances: web-prod-01 (i-bp1a2b3c...) and api-prod-02 (i-bp2x4y5z...).

Scenario 2: Run a Remote Command and Analyze the Result

User prompt:

Check whether i-bp1a2b3c4d5e6f has enough disk space.

Agent execution:

workbench exec -i i-bp1a2b3c4d5e6f -c "df -h" --output json

Simplified response:

{
  "output": "Filesystem      Size  Used Avail Use% Mounted on\n/dev/vda1        40G   36G  4.0G  90% /\n/dev/vdb1       100G   20G   80G  20% /data\n",
  "stderr": "",
  "exit_code": 0
}

Agent analysis: The root / partition is 90% used, with 4.0G remaining, which is close to its limit. We recommend that you clean up logs or expand the system disk. The /data partition is 20% used and has ample capacity.

Scenario 3: Transfer Files

User prompt:

Deploy ./app-2.0.tar.gz to the /opt/deploy directory on i-bp1a2b3c4d5e6f, then extract and verify it.

Agent execution (calls in sequence):

workbench upload ./app-2.0.tar.gz /opt/deploy/app-2.0.tar.gz -i i-bp1a2b3c4d5e6f
workbench exec -i i-bp1a2b3c4d5e6f -c "cd /opt/deploy && tar xzf app-2.0.tar.gz" --output json
workbench exec -i i-bp1a2b3c4d5e6f -c "ls -lh /opt/deploy/app-2.0/" --output json

Agent summary: The file was uploaded successfully. Extraction completed with exit code 0. The directory contains bin/, config/, and app.jar (120M). The deployment is complete.

Permissions and Security Recommendations

Use a dedicated RAM user or role for the AI agent: Separate the agent's credentials from those used by people. This makes it easier to distinguish "human operations" from "agent operations" in audit logs and to quickly locate the source of any issue.
Use a least-privilege policy and narrow the scope by Resource: Grant the agent only the Actions it needs, and use instance ARNs to narrow the Resource to specific instances, so that a mistaken operation does not spread to other instances.
Enable human-in-the-loop (HITL) confirmation: The agent mode built into workbench connect requires Y/n confirmation before running any command by default. For external AI tools, we recommend that you also enable user confirmation before command execution.
Prefer RamRoleArn in production: Agent scenarios often run for long periods and use credentials frequently, so a leaked static AccessKey pair carries high risk. Prefer RamRoleArn or CredentialsURI so that credentials are refreshed automatically.

FAQ

How Do I Troubleshoot a "command not found" Error After the Agent Loads the Skill

Cause: When the AI tool runs a child process, the shell environment it uses does not inherit the PATH of your user shell, so it cannot find the workbench binary.

Solution:

Use the absolute path /usr/local/bin/workbench (Linux/macOS) or C:\Program Files\workbench\workbench.exe (Windows).
Explicitly declare the binary path in the skill definition or system prompt.
Check how the AI tool is launched and whether it inherits your shell profile (~/.bashrc or ~/.zshrc).

How Do I Limit the Large Number of Sessions Caused by the Agent Retrying in a Loop

Cause: When the agent encounters an error, it retries repeatedly and creates a new session each time, gradually consuming server-side resources.

Solution:

In the skill or prompt, instruct the agent to immediately report an error to you without automatically retrying when it encounters a non-retryable error such as authentication failure or a non-existent instance (determined based on the message field of --output json).
Sessions are automatically reclaimed after about 30 minutes of idle timeout. When you do not need to keep a session for a long time, have the agent close it with /exit as soon as it is done.
Periodically run workbench session close --all or workbench daemon stop to clean up leftover sessions.

How Do I Force the Agent to Use Only --output json

Cause: By default, the agent may use text output, which leads to unstable parsing.

Solution: In the skill definition or system prompt, explicitly require the agent to append --output json to all workbench command calls and to parse results according to the JSON schema: on success, the fields are output, stderr, and exit_code; on failure, it outputs {code, message}.

References

Connect to an instance by using Workbench CLI: The parent topic, which covers the tool positioning and a quick start.
Install Workbench CLI and configure credentials: CLI installation and credential/permission configuration.
Manage ECS instances by using Workbench CLI: Detailed descriptions of each command and troubleshooting (including how to use the AI assistant within a connect session).