| name | ags |
| description | Reference Agent Skill example for Tencent Cloud AGS / Agent Runtime workflows using the agr CLI. Covers AGS sandbox tools and instances, code or shell execution in AGS, file transfer, browser/mobile sandboxes, storage mounts, API keys, image pre-cache, debug instances, tool fork, and raw AGS Cloud API workflows. Do not use for generic local shell, Docker, Kubernetes, or non-Tencent Cloud sandbox tasks. |
| when_to_use | Trigger on AGS, Agent Runtime, agr, Tencent Cloud sandbox, 腾讯云沙箱, AGS 沙箱, code execution, shell execution, file transfer, browser sandbox, mobile sandbox, CFS/COS/Image storage mounts, API keys, image pre-cache, debug instance, tool fork, or AGS Cloud API requests. |
AGS With agr
Use agr for all AGS work.
Start Here
First check the local CLI and credentials:
command -v agr
agr version -o json
agr status -o json
If agr is missing or outdated, install or upgrade it before running AGS workflows.
Requirements
- agr CLI (latest) — run
agr version -o json to check. Always use the latest release; see Install below if missing or outdated.
- Tencent Cloud SecretId/SecretKey — from CAM Console. Temporary STS credentials also supported via
TENCENTCLOUD_TOKEN.
- Config:
~/.agr/config.toml by default, or --config /path/to/config.toml.
Install
If agr is missing or outdated, install or upgrade to the latest release:
curl -fsSL https://github.com/TencentCloudAgentRuntime/ags-cli/releases/latest/download/install.sh | sh
go install github.com/TencentCloudAgentRuntime/ags-cli/cmd/agr@latest
Verify: agr version. If the installed version is not the latest, re-run the install command above.
Configure Credentials
export TENCENTCLOUD_SECRET_ID="..."
export TENCENTCLOUD_SECRET_KEY="..."
agr init --secret-id "$TENCENTCLOUD_SECRET_ID" --secret-key "$TENCENTCLOUD_SECRET_KEY" --overwrite -o json
agr status -o json
agr doctor -o json
Temporary STS credentials:
export TENCENTCLOUD_SECRET_ID="tmp-id"
export TENCENTCLOUD_SECRET_KEY="tmp-key"
export TENCENTCLOUD_TOKEN="tmp-session-token"
Or pass --token on any command, or agr config set token=<token>.
Config priority: --flag > env vars > ~/.agr/config.toml > defaults. Use agr status to inspect resolved values.
Safety Rules
- If the user explicitly asks to create, fork, run, or debug an AGS resource, proceed with temporary, clearly named resources.
- Confirm before deleting resources, creating long-lived resources, using unclear billing/permission settings, or changing non-temporary production resources.
- Use explicit
--timeout for temporary instances.
- Clean up temporary Instances and Tools with
instance delete and tool delete.
- Do not print or commit
SecretId, SecretKey, API keys, tokens, or RoleArn values.
- Prefer
--tool-id in scripts. Use --tool-name only for known-unique temporary resources.
- Use
-o json for automation. Use --stream -o ndjson only for streaming code run / exec.
Choose The Right Reference
Keep this file as the core workflow. Load extra files only when the task needs them:
| Need | Read |
|---|
| COS/CFS/Image mount JSON and path rules | references/mount-templates.md |
| VPC networking, private subnets, security groups, private service access | references/vpc-networking.md |
| Custom-image services, ports, probes, resources, env, registry access | references/custom-images.md |
| Browser, mobile, API keys, raw API, image pre-cache, interactive login/proxy | references/advanced-workflows.md |
| Statuses, errors, CLI drift, cleanup problems | references/troubleshooting.md |
Common Task Patterns
- Run code once: check
agr status, create or reuse a code-interpreter Tool, create an Instance with --timeout, wait for RUNNING, run instance code run, then delete temporary resources.
- Work with files: create or reuse an Instance, upload local files, run code or shell, download artifacts, then delete temporary resources.
- Fork an existing Tool: inspect the source Tool with
tool get, choose a unique new --tool-name, pass only the intended overrides to tool fork, verify the fork with tool get.
- Add storage while creating or forking a Tool: read references/mount-templates.md, include
--storage-mounts or a full --request, ensure RoleArn is present when the mount requires it, then create a test Instance.
- Create a custom-image service: read references/custom-images.md, use a full request JSON with image, command, ports, resources, and probe, then create an Instance and verify the service with
instance proxy or exec.
- Use VPC networking: read references/vpc-networking.md, collect subnet/security group IDs and the private target to test, then create or fork a new Tool with
NetworkMode: "VPC". Do not update an existing Tool into VPC mode.
- Debug a Tool: verify the source Tool has
RoleArn, run instance debug, wait for RUNNING, and use login or proxy only when the user asks for an interactive session.
Mental Model
| Object | Meaning |
|---|
| Tool | Reusable sandbox template: type, network, timeout, storage, image/custom config. |
| Instance | Running sandbox created from a Tool. Code, shell, files, ports, browser/mobile happen here. |
| API Key | Credential for E2B SDK / MCP paths, not Cloud API management. |
| Sandbox Token | Short-lived access credential for one Instance. |
CLI / Cloud API management uses Tencent Cloud SecretId / SecretKey (plus optional STS Token) with CAM permissions.
Output Rules
JSON responses use an agr.v1 envelope with Status, Data, Failure, Warnings, and Meta.
agr tool list --limit 20 -o json
agr tool list --limit 20 -o json --jq '.Data'
Rules:
--jq requires -o json.--stream is incompatible with -o json; use text or -o ndjson.agr instance login and agr instance proxy are interactive and do not return JSON.- On failure, inspect
.Failure.Code / .Failure.Hint, then run agr explain <CODE> -o json.
- Server-side errors now include
RequestId alongside Code and Message.
Exit codes: 0 success, 1 error, 2 usage, 4 auth, 255 remote_execution_failed. See agr schema -o json --jq '.Data.ExitCodes' for full list.
Create A Tool
Use CLI short type names: browser, code-interpreter, mobile, osworld, custom. Do not pass Cloud API enum values.
tool_name="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')
agr tool get "$tool_id" -o json
Key flags for tool create:
| Flag | Type | Notes |
|---|
--tool-name | string | Required. Must be unique within your AppId. Use a timestamp+PID suffix to avoid collisions. |
--tool-type | string | Required. One of: browser, code-interpreter, mobile, osworld, custom. |
--network-configuration | JSON | {"NetworkMode":"SANDBOX|PUBLIC|VPC"}. VPC mode also needs VpcConfig.SubnetIds and VpcConfig.SecurityGroupIds. |
--default-timeout | duration | Default instance timeout, e.g. 30m, 1h, 2h30m. Instances inherit this unless overridden on instance create. |
--storage-mounts | JSON / @file | Array of mount objects. See references/mount-templates.md for COS/CFS/Image examples. Requires --role-arn when the storage source needs cloud access. |
--role-arn | string | CAM role ARN required for COS/CFS mounts, private image registries, and debug instances. Format: qcs::cam::uin/<uin>:roleName/<name>. |
--tags | JSON / @file | Array of {"Key":"...","Value":"..."} objects for resource tagging. |
--generate-skeleton | — | Print a full JSON skeleton for --request. Use this first for complex configurations. |
--request | JSON / @file / - | Supply the full request body as JSON when many nested fields are needed. |
Network modes:
| Mode | Use |
|---|
SANDBOX | No Internet/VPC outbound; local code or mounted data. |
PUBLIC | Internet access for packages, APIs, public web. |
VPC | Private subnet/security group access. |
For custom images, VPC configs, tags, storage mounts, or many nested fields, start from the skeleton:
agr tool create --generate-skeleton > tool.json
agr tool create --request @tool.json -o json
tool create behavior notes:
- Tool name must be unique in your AppId; the create call fails immediately with a name conflict error if it already exists.
--storage-mounts and --role-arn are independent flags; both can be supplied alongside --request.--network-configuration in --request overrides the --network-configuration flag if both are passed. Prefer one or the other.
tool list filters:
agr tool list --tool-type code-interpreter -o json
agr tool list --limit 20 -o json --jq '.Data.Items[].ToolId'
Fork A Tool
Copy an existing Tool's settings into a new Tool with optional overrides:
agr tool get "$source_tool_id" -o json
forked_id=$(agr tool fork "$source_tool_id" \
--tool-name "forked-$(date +%s)-$$" \
--network-configuration '{"NetworkMode":"PUBLIC"}' \
-o json --jq '.Data.ToolId')
agr tool get "$forked_id" -o json
agr tool fork copies all creatable settings from the source. Pass any tool create flags to override specific fields. For CFS/COS/Image mounts while forking, read references/mount-templates.md.
Update A Tool
agr tool update "$tool_id" --description "Updated description" -o json
agr tool list -o json
agr tool get "$tool_id" -o json
Tool names cannot be updated. Use tool update only for supported mutable fields such as description, tags, network configuration, and custom configuration. Do not update an existing Tool into VPC mode; create or fork a new Tool with VPC networking instead.
agr tool update does not expose a direct --storage-mounts flag. If the user wants to add or replace storage mounts on an existing Tool, prefer forking it into a new Tool with the intended --storage-mounts; see references/mount-templates.md.
Create And Manage An Instance
instance_id=$(agr instance create \
--tool-id "$tool_id" \
--timeout 30m \
-o json --jq '.Data.InstanceId')
agr instance get "$instance_id" -o json
Key flags for instance create:
| Flag | Type | Notes |
|---|
--tool-id | string | Required (or --tool-name). Specifies the Tool template to instantiate. |
--tool-name | string | Alternative to --tool-id. Use only for known-unique tool names. |
--timeout | duration | Override the Tool's default timeout, e.g. 30m, 1h, 2h30m. Always set this for temporary instances. |
--mount-options | JSON / @file / - | Per-instance mount overrides. Can only reference mount names already defined in the Tool's StorageMounts. Supports MountPath, SubPath, ReadOnly overrides. |
--metadata | JSON / @file / - | Arbitrary key-value metadata attached to the instance. |
--auth-mode | string | DEFAULT (inherited from Tool), TOKEN (sandbox token required), NONE (no auth), PUBLIC (no auth, public access). |
--mount-options lets you re-use one Tool mount under multiple paths in a single instance run:
agr instance create \
--tool-id "$tool_id" \
--timeout 30m \
--mount-options '[
{"Name":"cos-assets","MountPath":"/workspace/input","SubPath":"run-001","ReadOnly":true},
{"Name":"cos-assets","MountPath":"/workspace/output","SubPath":"run-002","ReadOnly":false}
]' \
-o json --jq '.Data.InstanceId'
Instance status values:
Instance responses may include these status values:
STARTING, RUNNING, FAILED, STOPPING, STOPPED,
STARTING_FAILED, STOPPING_FAILED,
PAUSED, PAUSE_FAILED, RESUME_FAILED
Some command help text may list only a subset of status filter values. If status filtering is needed, prefer agr instance list --help / agr schema -o json for the installed CLI's accepted filter values.
Only RUNNING is safe for code, shell, file, browser/mobile, or port operations. STARTING is not ready — poll instance get before proceeding.
Useful instance list filters:
agr instance list --tool-id "$tool_id" -o json
agr instance list --filters '[{"Name":"Status","Values":["RUNNING"]}]' -o json
Lifecycle:
agr instance update "$instance_id" --timeout 1h -o json
agr instance pause "$instance_id" -o json
agr instance resume "$instance_id" -o json
agr instance delete "$instance_id" --ignore-not-found -o json
Common pitfalls:
| Problem | Cause | Fix |
|---|
| Code/exec fails with "instance not ready" | Called before status is RUNNING | Always check status == RUNNING before sending work |
--mount-options name not found | Name not in Tool's StorageMounts | Check tool get to see defined mount names |
--role-arn missing for storage mount | Tool lacks CAM role | Add --role-arn when creating or forking the Tool |
Debug An Instance
Creates a temporary debug Tool (start command switched to /envd, envd image mounted), then starts an Instance from it. The source Tool must have RoleArn configured.
debug_id=$(agr instance debug \
--tool-id "$tool_id" \
--timeout 30m \
-o json --jq '.Data.InstanceId')
| Flag | Notes |
|---|
--tool-id / --tool-name | Identify the source Tool. |
--timeout | Debug instance lifetime (default 1h). |
--mount-options | JSON / @file / - — per-instance mount overrides. |
--metadata | JSON / @file / - — arbitrary metadata. |
--custom-configuration | JSON / @file / - — custom start config overrides. |
Run Code Or Shell
agr instance code run "$instance_id" -l python -c "print('hello')" -o json
agr instance code run "$instance_id" -l bash -c "echo hello" -o json
agr instance exec "$instance_id" -o json -- pwd
agr instance exec "$instance_id" -o json --cwd /workspace --env APP_ENV=prod -- python app.py
Streaming:
agr instance code run "$instance_id" --stream -o ndjson -c "import time; [print(i) or time.sleep(1) for i in range(3)]"
agr instance exec "$instance_id" --stream -o ndjson -- tail -f /var/log/app.log
Temporary one-shot:
agr instance code run --create-temp-instance --tool-id "$tool_id" -c "print(42)" -o json
--cleanup options: always (default), success, never. JSON output includes Data.ExecutionContext.SandboxInstanceId and Data.ExecutionContext.Cleanup.
Supported code run languages: python, javascript, typescript, r, java, bash.
Transfer Files
agr instance file upload "$instance_id" ./local.csv /workspace/local.csv -o json
agr instance file download "$instance_id" /workspace/result.json ./result.json -o json
Both commands support --user.
Manage Config
agr config show
agr config set region=ap-beijing
agr config set token=<sts-session-token>
agr config path
Use agr status to verify resolved values including credentials.
Clean Up
agr instance delete "$instance_id" --ignore-not-found -o json
agr tool delete "$tool_id" -o json || true
Deleting an Instance or Tool does not delete COS objects, CFS data, or registry images.
Troubleshoot First
agr status -o json
agr doctor -o json
agr schema -o json
agr explain AUTH_FAILED -o json
agr instance create --network-configuration --help
agr instance list -o json --debug
Useful global flags: --debug (verbose stderr), --non-interactive (suppress prompts in scripts), --no-color, --region, --domain, --cloud-endpoint.
If public docs and the installed CLI disagree, trust agr --help / agr schema -o json for command syntax and product docs for concept meaning.
