Agent Run：使用 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