智能体 AgentRun：使用 AgentRun CLI 在命令行终端和 CICD 环境中管理 AgentRun

适用场景

典型使用场景包括：

• 在本地终端一条命令拉起 Super Agent 并直接对话。

• 用 YAML 声明式创建或更新 Super Agent，把配置纳入版本管理。

• 从容器镜像部署 Agent Runtime，或先在云上构建镜像再部署。

• 把已有 Runtime 导出为可再次 apply 的 YAML，方便复制、迁移和审计。

• 通过脚本以 JSON、YAML 或 quiet 格式消费命令输出结果。

CLI 入口命令是 ar，也可以使用完整命令名 agentrun，下文默认使用 ar。如果希望通过控制台可视化创建 Agent，参见快速创建Agent（无代码）。

安装 CLI

推荐直接安装预编译二进制，无需本地 Python 环境。

Linux / 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

安装完成后验证：

ar --version
# 或
agentrun --version

也可以通过 PyPI 安装：

pip install agentrun-cli

如果需要固定版本，可在安装脚本前设置 AGENTRUN_VERSION；如果需要指定安装目录，可设置 AGENTRUN_INSTALL。重新执行安装脚本即可覆盖升级到最新版本。卸载时删除 $AGENTRUN_INSTALL 目录下的 ar 二进制文件即可。

配置凭证

所有 CLI 命令都依赖 AccessKey 凭证和本地 profile 配置。首次使用前需完成以下一次性配置。

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

一条命令拉起 Super Agent

使用 ar super-agent 相关命令前，需要先在 RAM 控制台完成 AliyunAgentRunSuperAgentRole 服务角色授权。AgentRun 通过该角色（信任主体 agentrun.fc.aliyuncs.com）管理运行时资源，角色附加以下系统策略：

• AliyunAgentRunInvokeOnlyAccess（AgentRun 调用权限）

• AliyunAgentRunReadOnlyAccess（AgentRun 只读权限）

打开以下授权链接，在 RAM 控制台单击一键授权完成角色创建：

创建 AliyunAgentRunSuperAgentRole

如果缺少该角色，ar super-agent run 或 ar super-agent apply 会在创建阶段失败。

快速在终端创建一个托管 Agent 并开始对话：

ar super-agent run --prompt "你是一个 Python 专家"

命令会创建一个 Super Agent 并进入交互式 REPL。创建时终端会输出 Agent 名称，格式为 super-agent-tmp-{时间戳}（例如 super-agent-tmp-20260420213045）。输入 /exit 或按 Ctrl+D 退出 REPL。退出后 Agent 会保留，后续可以使用该名称继续对话：

ar sa chat super-agent-tmp-20260420213045

super-agent 的短别名是 sa。常用命令：

若脚本只需获取 Assistant 回复文本，可以加 --text-only：

ar sa invoke my-helper -m "总结今天的告警" --text-only

用 YAML 声明式管理 Super Agent

把 Agent 配置写成 YAML，可以像管理代码一样管理 Agent：

apiVersion: agentrun/v1
kind: SuperAgent
metadata:
  name: my-helper
  description: "我的助手"
spec:
  prompt: "你是我的得力助手"
  tools:
    - mcp-time-sa
  skills: []
  sandboxes: []
  workspaces: []
  subAgents: []

保存为 superagent.yaml 后执行：

ar sa apply -f superagent.yaml

首次运行会创建 Agent，后续运行会更新同名 Agent。多份 YAML 可以用 --- 分隔后一次性部署。

如果想先检查 YAML 会被渲染成什么请求，不实际调用服务端：

ar sa render -f superagent.yaml

从容器镜像部署 Agent Runtime

如果 Agent 已经打包成容器镜像，可以用 ar runtime apply 部署 Agent Runtime。runtime 的短别名是 rt。

最小 YAML：

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

部署：

ar runtime apply -f runtime.yaml

部署后，通过以下命令验证 Runtime 是否就绪。--wait 参数会持续轮询直到 Runtime 进入就绪状态或超时：

ar rt status my-agent --wait

当 YAML 省略 spec.endpoints 时，CLI 会自动注入一个名为 default、指向 LATEST 版本的 endpoint。cpu、memory、port 未显式填写时，CLI 也会注入默认值，避免后端因为空值拒绝请求。具体默认值参见 AgentRun CLI 仓库中的用户手册。

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

导出现有 Runtime，生成可复用 YAML

如果控制台或其他流程中已有 Runtime，可以用 CLI 导出为 YAML：

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

导出的 YAML 可以直接用于 ar runtime apply。常见用法是复制一份 Runtime：

ar runtime export my-agent -f copied-runtime.yaml
# 编辑 copied-runtime.yaml，把 metadata.name 改成 my-agent-copy
ar runtime apply -f copied-runtime.yaml

导出时会刻意省略 ID、ARN、版本、状态、时间戳等服务端状态字段。镜像仓库密码等敏感字段默认不会导出；只有明确需要完整导出时才使用：

ar runtime export my-agent --include-secrets

CLI 部署和管理的 Agent 同样支持集成与发布，参见Agent集成与发布。

输出格式和退出码

CLI 默认输出 JSON，方便脚本和自动化 Agent 解析。也可以通过全局参数切换输出格式：

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

常见退出码：

错误信息会写到 stderr，通常为 JSON 格式，便于 CI 判断失败原因。

常用命令速查

实践建议

• 本地调试优先用 ar sa run 或 ar sa chat，确认 Agent 行为后再写 YAML。

• 生产和 CI 场景优先使用 apply，把 YAML 放进代码仓库，变更可审计、可回滚。

• runtime export 适合迁移和复制，但不要把导出的敏感字段直接提交到仓库。

• 根命令全局参数要放在命令组前，例如 ar --profile staging rt list，不要写成 ar rt list --profile staging。

• 非交互脚本中建议使用 --output json 或 --output quiet，避免解析人类可读文本。

相关链接

• AgentRun 控制台

• AgentRun CLI GitHub

• AgentRun Python SDK