Agent Run:Gunakan CLI AgentRun untuk mengelola AgentRun di terminal dan pipeline CI

Skenario

Skenario umum meliputi:

• Luncurkan Super Agent dari terminal lokal dengan satu perintah dan segera mulai percakapan.

• Buat atau perbarui Super Agent secara deklaratif dalam format YAML dan tempatkan konfigurasinya di bawah kendali versi.

• Deploy Agent Runtime dari gambar kontainer, atau bangun gambarnya di cloud terlebih dahulu lalu deploy.

• Ekspor runtime yang sudah ada ke dalam format YAML yang dapat Anda apply kembali, sehingga mempermudah penyalinan, migrasi, dan audit.

• Konsumsi output perintah dalam format JSON, YAML, atau quiet dari skrip.

Perintah utama CLI adalah ar. Anda juga dapat menggunakan nama perintah lengkap agentrun. Topik ini menggunakan ar secara default. Untuk membuat agent secara visual di konsol, lihat Buat agent dengan cepat (tanpa kode).

Instal CLI

Kami menyarankan Anda menginstal binary yang telah dikompilasi secara langsung, yang tidak memerlukan lingkungan Python lokal.

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

Setelah instalasi selesai, verifikasi instalasinya:

ar --version
# atau
agentrun --version

Anda juga dapat menginstal CLI dari PyPI:

pip install agentrun-cli

Untuk mengunci versi tertentu, atur AGENTRUN_VERSION sebelum menjalankan skrip instalasi. Untuk menentukan direktori instalasi, atur AGENTRUN_INSTALL. Jalankan kembali skrip instalasi untuk melakukan upgrade ke versi terbaru secara langsung. Untuk meng-uninstall CLI, hapus binary ar dari direktori $AGENTRUN_INSTALL.

Konfigurasi kredensial

Semua perintah CLI bergantung pada kredensial AccessKey dan profil lokal. Lakukan konfigurasi satu kali berikut sebelum menggunakan CLI untuk pertama kalinya.

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

Luncurkan Super Agent dengan satu perintah

Sebelum menggunakan perintah ar super-agent, Anda harus memberikan izin kepada role terkait layanan AliyunAgentRunSuperAgentRole di konsol RAM. AgentRun menggunakan role ini, yang entitas tepercayanya adalah agentrun.fc.aliyuncs.com, untuk mengelola sumber daya runtime. Kebijakan sistem berikut dilampirkan pada role tersebut:

• AliyunAgentRunInvokeOnlyAccess (izin pemanggilan AgentRun)

• AliyunAgentRunReadOnlyAccess (izin read-only AgentRun)

Buka tautan otorisasi berikut dan klik One-click Authorization di konsol RAM untuk membuat role tersebut:

Buat AliyunAgentRunSuperAgentRole

Jika role tersebut tidak ada, ar super-agent run atau ar super-agent apply akan gagal selama fase pembuatan.

Buat agent terkelola dengan cepat di terminal dan mulai percakapan:

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

Perintah ini membuat Super Agent dan memasuki REPL interaktif. Terminal mencetak nama agent selama pembuatan dalam format super-agent-tmp-{timestamp}, misalnya super-agent-tmp-20260420213045. Untuk keluar dari REPL, masukkan /exit atau tekan Ctrl+D. Agent tetap tersimpan setelah Anda keluar, dan Anda dapat menggunakan namanya untuk melanjutkan percakapan nanti:

ar sa chat super-agent-tmp-20260420213045

Alias pendek dari super-agent adalah sa. Perintah umum:

Jika skrip Anda hanya membutuhkan teks balasan asisten, tambahkan --text-only:

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

Kelola Super Agent secara deklaratif dalam YAML

Tulis konfigurasi agent dalam format YAML agar Anda dapat mengelola agent seperti mengelola kode:

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: []

Simpan file sebagai superagent.yaml, lalu jalankan perintah berikut:

ar sa apply -f superagent.yaml

Jalankan pertama kali akan membuat agent, sedangkan jalanan berikutnya akan memperbarui agent dengan nama yang sama. Anda dapat memisahkan beberapa dokumen YAML dengan --- dan mendeploynya sekaligus.

Untuk memeriksa permintaan apa yang dihasilkan dari YAML tanpa benar-benar memanggil server:

ar sa render -f superagent.yaml

Deploy Agent Runtime dari gambar kontainer

Jika agent Anda sudah dikemas sebagai gambar kontainer, Anda dapat menjalankan ar runtime apply untuk mendeploy Agent Runtime. Alias pendek dari runtime adalah rt.

YAML minimal:

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

Deploy runtime:

ar runtime apply -f runtime.yaml

Setelah deployment, jalankan perintah berikut untuk memeriksa apakah runtime sudah siap. Parameter --wait terus-menerus melakukan polling hingga runtime siap atau operasi timeout:

ar rt status my-agent --wait

Jika spec.endpoints dihilangkan dari YAML, CLI secara otomatis menyuntikkan endpoint bernama default yang mengarah ke versi LATEST. Jika cpu, memory, atau port tidak secara eksplisit ditentukan, CLI juga menyuntikkan nilai default untuk mencegah backend menolak permintaan karena nilai kosong. Untuk nilai default spesifiknya, lihat manual pengguna di repositori 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

Ekspor runtime yang sudah ada ke YAML yang dapat digunakan kembali

Jika runtime sudah ada di konsol atau proses lain, Anda dapat menggunakan CLI untuk mengekspornya ke format YAML:

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

YAML hasil ekspor dapat langsung digunakan dengan ar runtime apply. Penggunaan umumnya adalah menyalin runtime:

ar runtime export my-agent -f copied-runtime.yaml
# Edit copied-runtime.yaml dan ubah metadata.name menjadi my-agent-copy
ar runtime apply -f copied-runtime.yaml

Ekspor sengaja menghilangkan field status sisi server seperti ID, ARN, versi, status, dan timestamp. Field sensitif seperti kata sandi repository image tidak diekspor secara default. Gunakan perintah berikut hanya jika Anda secara eksplisit membutuhkan ekspor lengkap:

ar runtime export my-agent --include-secrets

Agent yang dideploy dan dikelola oleh CLI juga mendukung integrasi dan rilis. Untuk informasi lebih lanjut, lihat Integrasi dan penerbitan agent.

Format output dan exit code

Secara default, CLI menghasilkan output dalam format JSON, sehingga memudahkan skrip dan agent otomatis untuk mengurai hasilnya. Anda juga dapat mengubah format output menggunakan parameter global:

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

Exit code umum:

Pesan error ditulis ke stderr, biasanya dalam format JSON, sehingga pipeline CI dapat menentukan penyebab kegagalan.

Referensi cepat perintah

Praktik terbaik

• Untuk debugging lokal, gunakan ar sa run atau ar sa chat terlebih dahulu, lalu tulis YAML setelah Anda memastikan perilaku agent.

• Di skenario produksi dan CI, gunakan apply dan simpan YAML di repositori kode agar perubahan dapat diaudit dan dibalikkan.

• runtime export cocok untuk migrasi dan penyalinan, tetapi jangan melakukan commit field sensitif hasil ekspor ke repositori.

• Letakkan parameter global tingkat root sebelum grup perintah. Misalnya, gunakan ar --profile staging rt list alih-alih ar rt list --profile staging.

• Di skrip non-interaktif, gunakan --output json atau --output quiet untuk menghindari penguraian teks yang dapat dibaca manusia.

Referensi

• Konsol AgentRun

• AgentRun CLI di GitHub

• AgentRun Python SDK