AGR CLI

中文文档

AGR CLI manages Tencent Cloud Agent Runtime instances, tools, API keys, and data-plane operations from the agr command.

Installation

From source

git clone https://github.com/TencentCloudAgentRuntime/ags-cli.git
cd ags-cli
make build
sudo cp agr /usr/local/bin/agr

Using go install

go install github.com/TencentCloudAgentRuntime/ags-cli/cmd/agr@latest

The installed command name is agr.

Prerequisites

1. A Tencent Cloud account
2. AGR (Agent Runtime) service enabled
3. API credentials (SecretID / SecretKey) — obtain from CAM Console

Initialize CLI credentials

export TENCENTCLOUD_SECRET_ID="your-secret-id"
export TENCENTCLOUD_SECRET_KEY="your-secret-key"

agr init \
  --secret-id "$TENCENTCLOUD_SECRET_ID" \
  --secret-key "$TENCENTCLOUD_SECRET_KEY"

agr init only writes local CLI configuration under ~/.agr/config.toml; it does not create remote resources or modify the current project directory.

Quick Start

export TENCENTCLOUD_SECRET_ID="your-secret-id"
export TENCENTCLOUD_SECRET_KEY="your-secret-key"

agr init \
  --secret-id "$TENCENTCLOUD_SECRET_ID" \
  --secret-key "$TENCENTCLOUD_SECRET_KEY"

tool_name="quickstart-code-$(date +%s)-$$"
tool_id=$(agr tool create \
  --tool-name "$tool_name" \
  --tool-type code-interpreter \
  --network-configuration '{"NetworkMode":"SANDBOX"}' \
  -o json --jq '.Data.ToolId')

instance_id=$(agr instance create --tool-id "$tool_id" -o json --jq '.Data.InstanceId')
agr instance code run "$instance_id" -c "print('Hello, World!')"
agr instance delete "$instance_id" --ignore-not-found
agr tool delete "$tool_id" || true

The example creates a unique tool name first because tool names must be unique within the current AppId.

Temporary sandbox workflow

agr instance code run and agr instance exec accept --create-temp-instance to spin up a sandbox just for this single execution, and clean it up automatically. The referenced tool must already exist; create one first with agr tool create, then pass --tool-name or --tool-id:

# Create a temporary instance, run a snippet, delete it always (cleanup=always is the default).
agr instance code run \
  --create-temp-instance \
  --tool-id "$tool_id" \
  -c "print('hello')"

# Same workflow, but keep the temporary instance for debugging.
agr instance exec \
  --create-temp-instance \
  --tool-id "$tool_id" \
  --cleanup never \
  -- python -V

--cleanup accepts always (default), success, or never. To keep the temporary instance after the run, use --cleanup never. There is no --keep-temp-instance.

The JSON output of these commands includes Data.ExecutionContext.SandboxInstanceId, Data.ExecutionContext.TemporarySandboxInstance and Data.ExecutionContext.Cleanup so scripts can inspect the workflow.

Cloud endpoint vs data-plane domain

Flag	Default	Controls
--cloud-endpoint	ags.tencentcloudapi.com	Control-plane API endpoint
--domain	tencentags.com	Data-plane domain (browser, exec)

--cloud-endpoint affects every control-plane call (regular resource commands and agr api call). --domain only affects data-plane access. Both can also be set via cloud_endpoint / domain in ~/.agr/config.toml or AGR_CLOUD_ENDPOINT / AGR_DOMAIN environment variables.

Low-level API access

For undocumented fields or debugging, use the raw API channel:

agr api call DescribeSandboxInstanceList --request '{"Limit":1}' -o json
agr api call StartSandboxInstance --request @start.json
agr api call StopSandboxInstance --request - < stop.json

Command Overview

agr                              Print help
agr init                         Initialize local CLI config and credentials
agr version                      Version info
agr status                       Current configuration status
agr schema [command]             Machine-readable command schema
agr doctor                       Diagnose configuration and connectivity
agr explain <CODE>               Explain errors and fixes

agr instance create              Create a new instance
agr instance list                List instances
agr instance get <id>            Get instance details
agr instance update <id>         Update timeout/metadata
agr instance pause <id>          Pause an instance
agr instance resume <id>         Resume an instance
agr instance delete <id>         Delete instance(s)

agr instance code run <id>       Execute code in an existing instance
agr instance exec <id> -- CMD    Execute shell command in an existing instance
agr instance file upload <id>    Upload file to an existing instance
agr instance file download <id>  Download file from an existing instance
agr instance login <id>          PTY terminal session
agr instance browser vnc <id>    Show VNC URL
agr instance proxy <id> PORT     Forward instance port to localhost
agr instance mobile ...          Mobile ADB operations

agr tool list/create/get/update/delete
agr apikey create/list/delete
agr pre-cache-image-task create|get
agr completion bash|zsh|fish|powershell

Machine-readable output and --jq

Commands that support -o json return one agr.v1 envelope on stdout:

{
  "SchemaVersion": "agr.v1",
  "Command": "instance.create",
  "Status": "succeeded",
  "Data": { "InstanceId": "sandbox-xxx", "ToolName": "my-tool" },
  "Failure": null,
  "Warnings": [],
  "Meta": { "DurationMs": 123 }
}

Examples:

agr instance create --tool-id "$tool_id" -o json --jq '.Data.InstanceId'
agr instance list -o json --jq '.Data.Items[].InstanceId'
agr status -o json --jq '.Data.Region'
agr schema -o json --jq '.Data.ExitCodes'

--jq must be used with -o json.

Streaming

Only instance code run and instance exec support machine-readable streaming:

agr instance code run "$id" -c "print(1)" --stream -o ndjson
agr instance exec "$id" --stream -o ndjson -- tail -f app.log

Each stdout line is one agr.events.v1 JSON event.

Exit Codes

Exit	Kind	Description
0	success	OK
1	error	Non-usage, non-auth CLI or API failure; inspect Failure.Kind for details
2	usage	Invalid args, flags, input, or unsupported output mode
4	auth	Missing credentials, authentication failure, or permission failure
255	remote_execution_failed	Remote code execution failure

instance exec and instance mobile adb may also pass through downstream process exit codes in the range 0-255.

See agr schema -o json --jq '.Data.ExitCodes' for the full list.

Global Flags

--config          Config file path (default: ~/.agr/config.toml)
-o, --output      Output format: text, json, or ndjson (`ndjson` only when explicitly passed to supported streaming commands)
--jq              jq expression (only with -o json)
--region          Tencent Cloud region (default: ap-guangzhou)
--cloud-endpoint  Control-plane API endpoint (default: ags.tencentcloudapi.com)
--domain          Data-plane domain (default: tencentags.com)
--secret-id       Tencent Cloud SecretID
--secret-key      Tencent Cloud SecretKey
--non-interactive Disable interactive behavior
--no-color        Disable ANSI color
--debug           Write debug diagnostics to stderr

Environment variables: TENCENTCLOUD_SECRET_ID, TENCENTCLOUD_SECRET_KEY, AGR_OUTPUT, AGR_REGION, AGR_CLOUD_ENDPOINT, AGR_DOMAIN, AGR_NON_INTERACTIVE, AGR_DEBUG, NO_COLOR.

AGR_OUTPUT is intended for default text or json output. For streaming, pass -o ndjson explicitly with agr instance code run --stream or agr instance exec --stream.

Configuration priority: --flag > environment variable > ~/.agr/config.toml > default. Use agr status to inspect resolved values and their sources.

Troubleshooting

agr status
agr doctor
agr explain AUTH_FAILED
agr schema instance.create -o json

License

See LICENSE.