Agent Run:Use the AgentRun CLI to manage AgentRun in terminals and CI pipelines

Scenarios

Typical scenarios include:

• Launch a Super Agent from a local terminal with a single command and start a conversation immediately.

• Declaratively create or update a Super Agent in YAML and place the configuration under version control.

• Deploy an Agent Runtime from a container image, or build the image in the cloud first and then deploy it.

• Export an existing runtime to YAML that you can apply again, which simplifies copying, migration, and auditing.

• Consume command output in JSON, YAML, or quiet format from scripts.

The CLI entry command is ar. You can also use the full command name agentrun. This topic uses ar by default. To create an agent visually in the console, see Create an agent with Quick Creation (no-code).

Install the CLI

We recommend that you install the precompiled binary directly, which does not require a local Python environment.

Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/Serverless-Devs/agentrun-cli/main/scripts/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/Serverless-Devs/agentrun-cli/main/scripts/install.ps1 | iex

After the installation is complete, verify it:

ar --version
# or
agentrun --version

You can also install the CLI from PyPI:

pip install agentrun-cli

To pin a specific version, set AGENTRUN_VERSION before you run the installation script. To specify the installation directory, set AGENTRUN_INSTALL. Run the installation script again to upgrade to the latest version in place. To uninstall the CLI, delete the ar binary from the $AGENTRUN_INSTALL directory.

Configure credentials

All CLI commands rely on AccessKey credentials and a local profile. Complete the following one-time configuration before you use the CLI for the first time.

ar config set access_key_id     LTAI5t...
ar config set access_key_secret ***
ar config set account_id        1234567890
ar config set region            cn-hangzhou

ar config set access_key_id LTAI-staging --profile staging
ar config set region        cn-shanghai  --profile staging

ar --profile staging runtime list

Launch a Super Agent with a single command

Before you use ar super-agent commands, you must grant permissions to the AliyunAgentRunSuperAgentRole service-linked role in the RAM console. AgentRun uses this role, whose trusted entity is agentrun.fc.aliyuncs.com, to manage runtime resources. The following system policies are attached to the role:

• AliyunAgentRunInvokeOnlyAccess (AgentRun invocation permissions)

• AliyunAgentRunReadOnlyAccess (AgentRun read-only permissions)

Open the following authorization link and click One-click Authorization in the RAM console to create the role:

Create AliyunAgentRunSuperAgentRole

If the role does not exist, ar super-agent run or ar super-agent apply fails during the creation phase.

Quickly create a managed agent in the terminal and start a conversation:

ar super-agent run --prompt "You are a Python expert"

The command creates a Super Agent and enters an interactive REPL. The terminal prints the agent name during creation in the super-agent-tmp-{timestamp} format, such as super-agent-tmp-20260420213045. To exit the REPL, enter /exit or press Ctrl+D. The agent is retained after you exit, and you can use its name to continue the conversation later:

ar sa chat super-agent-tmp-20260420213045

The short alias of super-agent is sa. Common commands:

If your script needs only the assistant's reply text, add --text-only:

ar sa invoke my-helper -m "Summarize today's alerts" --text-only

Declaratively manage a Super Agent in YAML

Write the agent configuration in YAML so that you can manage agents in the same way that you manage code:

apiVersion: agentrun/v1
kind: SuperAgent
metadata:
  name: my-helper
  description: "My assistant"
spec:
  prompt: "You are my capable assistant"
  tools:
    - mcp-time-sa
  skills: []
  sandboxes: []
  workspaces: []
  subAgents: []

Save the file as superagent.yaml and then run the following command:

ar sa apply -f superagent.yaml

The first run creates the agent, and subsequent runs update the agent that has the same name. You can separate multiple YAML documents with --- and deploy them at a time.

To check what request the YAML is rendered into without actually calling the server:

ar sa render -f superagent.yaml

Deploy an Agent Runtime from a container image

If your agent is already packaged as a container image, you can run ar runtime apply to deploy an Agent Runtime. The short alias of runtime is rt.

Minimal YAML:

apiVersion: agentrun/v1
kind: AgentRuntime
metadata:
  name: my-agent
spec:
  container:
    image: registry.cn-hangzhou.aliyuncs.com/my-ns/my-agent:v1

Deploy the runtime:

ar runtime apply -f runtime.yaml

After the deployment, run the following command to check whether the runtime is ready. The --wait parameter continuously polls until the runtime becomes ready or the operation times out:

ar rt status my-agent --wait

If spec.endpoints is omitted from the YAML, the CLI automatically injects an endpoint named default that points to the LATEST version. If cpu, memory, or port is not explicitly specified, the CLI also injects default values to prevent the backend from rejecting the request because of empty values. For the specific default values, refer to the user manual in the AgentRun CLI repository.

apiVersion: agentrun/v1
kind: AgentRuntime
metadata:
  name: my-agent
spec:
  container:
    image: registry.cn-hangzhou.aliyuncs.com/my-ns/my-agent:v1
    cloudBuild:
      dir: .
      setupScript: scripts/setup.sh
      baseContainerConfig:
        image: serverless-registry.cn-hangzhou.cr.aliyuncs.com/functionai/docker-image-builder-worker:20260514-111141-2d80effe

ar runtime apply -f runtime-build.yaml

ar runtime cloud-build -f runtime-build.yaml

Export an existing runtime to reusable YAML

If a runtime already exists in the console or in another process, you can use the CLI to export it to YAML:

ar runtime export my-agent -f copied-runtime.yaml

The exported YAML can be used directly with ar runtime apply. A common use is to copy a runtime:

ar runtime export my-agent -f copied-runtime.yaml
# Edit copied-runtime.yaml and change metadata.name to my-agent-copy
ar runtime apply -f copied-runtime.yaml

The export intentionally omits server-side state fields such as IDs, ARNs, versions, statuses, and timestamps. Sensitive fields such as image repository passwords are not exported by default. Use the following command only when you explicitly need a complete export:

ar runtime export my-agent --include-secrets

Agents that are deployed and managed by the CLI also support integration and release. For more information, see Agent integration and publishing.

Output formats and exit codes

By default, the CLI outputs JSON, which makes it easy for scripts and automated agents to parse the results. You can also switch the output format by using a global parameter:

ar --output table runtime list
ar --output yaml runtime get my-agent
ar --output quiet runtime get my-agent

Common exit codes:

Error messages are written to stderr, usually in JSON format, so that CI pipelines can determine the cause of a failure.

Command quick reference

Best practices

• For local debugging, use ar sa run or ar sa chat first, and write the YAML after you confirm the agent's behavior.

• In production and CI scenarios, use apply and store the YAML in a code repository so that changes are auditable and reversible.

• runtime export is suitable for migration and copying, but do not commit exported sensitive fields to a repository.

• Place root-level global parameters before the command group. For example, use ar --profile staging rt list instead of ar rt list --profile staging.

• In non-interactive scripts, use --output json or --output quiet to avoid parsing human-readable text.

References

• AgentRun console

• AgentRun CLI on GitHub

• AgentRun Python SDK