Memulai dengan Claude Managed Agents yang di-host sendiri

Dalam quickstart ini, Anda menjalankan Claude Managed Agents yang di-host sendiri di satu mesin dengan Docker Compose. Stack Compose terdiri dari server, database PostgreSQL-nya, dan sekumpulan worker yang menjalankan setiap sesi di “sandbox container” (container sandbox) miliknya sendiri. Setelah itu, Anda mengobrol dengan agen dari terminal Anda dan memastikan bahwa “tool calls” (panggilan alat) agen tersebut berjalan di dalam sandbox container. Anda kemudian dapat membuka sesi di konsol di server Anda.

Untuk produksi, Anthropic merekomendasikan dua Helm chart dari rilis ini. Lihat Menerapkan di Kubernetes.

Prasyarat

• Arsip rilis: Untuk meminta akses ke unduhan, hubungi tim akun Anthropic Anda.
• Kunci API Claude: Server menggunakannya untuk panggilan model. Buat kunci di Claude Console.
• Docker: Versi terbaru Docker Engine dengan plugin Compose (docker compose, bukan docker-compose versi lama).
• Host dengan setidaknya dua CPU: x86-64 atau Arm. Pada host yang lebih kecil, atur CMA_SANDBOX_CPUS ke jumlah CPU host tersebut saat Anda membuat .env.
• Akses jaringan saat pertama kali dijalankan: Build pertama mengambil dari Docker Hub, repositori paket Alpine, dan rilis GitHub.
• Alat: Di mesin tempat Anda menjalankan Docker, Anda memerlukan openssl dan CLI ant.

Menjalankan stack

1. 1

   Ekstrak arsip

   Ekstrak arsip, dan bekerjalah dari direktori compose di dalamnya. Dalam perintah tersebut, ganti <archive> dengan nama arsip Anda, tanpa .tar.gz.

   tar -xzf <archive>.tar.gz && cd <archive>/compose

   

   Jika umask Anda lebih ketat dari 022, binary kehilangan izin eksekusinya untuk pengguna lain, dan container server tidak dapat menjalankannya. Dalam hal ini, atur umask ke 022 lalu ekstrak arsip lagi.

2. 2

   Buat file .env

   Compose membaca secret stack dari file .env di sebelah docker-compose.yml. Buat file-nya:

   cat > .env <<EOF
   CMA_PG_PASSWORD=$(openssl rand -hex 32)
   ANTHROPIC_API_KEY=sk-ant-...
   CMA_SERVER__API_KEY=$(openssl rand -hex 32)
   CMA_STORE__CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
   EOF
   chmod 600 .env

   

   Buka .env di editor dan ganti sk-ant-... dengan kunci API Claude Anda. Blok tersebut menghasilkan sisanya: kata sandi database, kunci API server yang dikirim aplikasi Anda, dan kunci yang mengenkripsi secret yang disimpan server.

3. 3

   Jalankan container

   Build dan jalankan stack, lalu ikuti log server:

   docker compose up --build -d
   docker compose logs -f cma-server

   

   Ketika log menampilkan baris dengan msg="cma-server listening", tekan Ctrl+C untuk berhenti mengikutinya.

4. 4

   Periksa bahwa server sudah siap

   curl -s http://127.0.0.1:8400/cma-server/readyz

   

   Server yang siap menjawab dengan "status":"ready". Tepat setelah dimulai, server dapat menjawab "status":"degraded" selama beberapa detik sementara pemeriksaan pertamanya berjalan. Jika statusnya tetap degraded atau server menjawab "status":"not_ready", lihat Pemecahan masalah.

Jalankan sesi pertama Anda

Buat agen dan mengobrollah dengannya dari terminal Anda menggunakan CLI ant.

1. 1

   Arahkan CLI ke server Anda

   Buka terminal kedua di direktori yang sama, dan gunakan terminal itu khusus untuk ant. Perintah-perintah berikut mengatur ANTHROPIC_API_KEY ke kunci API server Anda, bukan kunci API Claude Anda, seperti yang dijelaskan di Memanggil API pada server yang di-host sendiri:

   export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
   export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)

   

   Tetap jalankan perintah docker compose di terminal pertama. Jika Anda menjalankan docker compose up di terminal ini, Compose meneruskan variabel-variabel ini ke server, dan server memanggil dirinya sendiri alih-alih Claude API.

2. 2

   Buat agen

   Simpan file yang ditampilkan setelah perintah sebagai quickstart-agent.md, lalu jalankan perintah tersebut. File ini memberikan alat bawaan kepada agen dan mengizinkannya menjalankan alat tersebut tanpa meminta persetujuan Anda terlebih dahulu.

   CLI

   

   ant apply --yes quickstart-agent.md

   quickstart-agent.md

   

   ---
   name: Quickstart agent
   model: claude-opus-5-5
   tools:
     - type: agent_toolset_20260401
   ---
   
   You are a helpful assistant.

   Perintah ini pertama-tama mencetak peringatan bahwa perintah tersebut could not determine the organization and workspace, dengan error 404, lalu membuat agen. Hal itu memang diharapkan di server Anda sendiri.

3. 3

   Mulai sesi

   Perintah-perintah ini menemukan agen dan environment milik stack, memulai sesi, dan menyimpan ID sesi di SESSION_ID. Stack menamai environment-nya compose-sandbox.

   AGENT_ID=$(ant beta:agents list --format raw \
     --transform 'data.#(name=="Quickstart agent").id' --raw-output)
   ENVIRONMENT_ID=$(ant beta:environments list --format raw \
     --transform 'data.#(name=="compose-sandbox").id' --raw-output)
   SESSION_ID=$(ant beta:sessions create --agent "$AGENT_ID" \
     --environment-id "$ENVIRONMENT_ID" --transform id --raw-output)

   
4. 4

   Minta agen menjalankan perintah

   Hubungkan terminal Anda ke sesi:

   ant beta:sessions connect "$SESSION_ID"

   

   Perintah ini membuka tampilan obrolan dari sesi. Kirim pesan ini:

   Run `hostname` with the bash tool and tell me the output.

   

   Agen membalas dengan hostname yang diawali cma-sandbox-. Itu adalah nama container sandbox yang menjalankan perintah tersebut, yang memastikan bahwa alat berjalan di sandbox dan bukan di mesin Anda.

5. 5

   Temukan container sandbox

   Biarkan obrolan tetap terbuka. Di terminal pertama, tampilkan daftar sandbox container:

   docker ps --filter label=cma-server.sandbox

   

   Daftar menampilkan container yang dilaporkan agen. Container keluar sekitar satu menit setelah sebuah giliran berakhir, dan pesan berikutnya dalam sesi memulai container baru. Jika daftarnya kosong, minta agen menjalankan hostname lagi, dan tampilkan daftar container lagi selagi agen membalas.

   Untuk keluar dari obrolan, tekan Ctrl+C di terminalnya. Sesi tetap berjalan.

Coba konsol di server Anda

Bagian ini opsional. Konsol memerlukan single sign-on. Untuk mencobanya, mulai ulang stack dengan penyedia sign-in tiruan dari rilis. Port 8080 di mesin Anda harus kosong.

1. 1

   Mulai ulang stack dengan penyedia sign-in tiruan

   Jalankan perintah-perintah ini di terminal pertama:

   export COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml
   docker compose up --build -d

   

   Baris export hanya berlaku untuk terminal pertama, jadi jalankan lagi di terminal baru mana pun yang Anda buka untuk docker compose. Untuk mengubah pengaturan server di stack ini, edit compose.config.oidc.yaml, bukan compose.config.yaml, lalu jalankan docker compose restart cma-server.

2. 2

   Buka sesi

   Di browser pada mesin yang sama, buka http://127.0.0.1:8400/, klik Continue with SSO, lalu pilih alice, administrator demo. Di sidebar, pilih Sessions, lalu pilih sesi tersebut.

   Halaman diperbarui seiring agen bekerja, dan Anda dapat mengirim pesan ke agen dari halaman tersebut.

Untuk juga membuat agen dan memulai sesi di konsol, lihat Menjalankan agen dari konsol.

Menghentikan stack

Di terminal pertama, jalankan perintah ini:

docker compose down --remove-orphans

Perintah ini menghapus container dan mempertahankan database. Untuk juga menghapus database, beserta setiap agen, sesi, dan riwayat sesi di dalamnya, jalankan docker compose down --remove-orphans -v.

Pemecahan masalah

• Arsip Anda tidak memiliki direktori compose: Arsip tersebut berisi rilis yang lebih lama, dan perintah di halaman ini tidak sesuai dengannya. Mintalah rilis terbaru kepada tim akun Anthropic Anda. Untuk memindahkan deployment yang sedang berjalan ke rilis terbaru, lihat Meningkatkan Claude Managed Agents yang di-host sendiri.
• Server tidak pernah aktif: Jalankan docker compose logs migrate. Container migrate sekali jalan membuat tabel database. Container tersebut harus keluar dengan status 0 sebelum server dimulai.
• Pemeriksaan kesiapan tetap degraded, atau setiap giliran gagal: Jika Anda menjalankan docker compose up di terminal tempat ANTHROPIC_BASE_URL bernilai http://127.0.0.1:8400, server memanggil dirinya sendiri alih-alih Claude API. Jalankan docker compose up -d lagi di terminal pertama, tempat variabel tersebut tidak diatur. Jika tidak demikian, log server menunjukkan apa yang gagal. Untuk membacanya, jalankan docker compose logs -f cma-server lagi.
• Pemeriksaan kesiapan menjawab not_ready: Dalam jawaban tersebut, temukan pemeriksaan dengan status failed:
  • upstream: Claude API menolak kunci API Claude Anda. Perbaiki ANTHROPIC_API_KEY di .env, lalu jalankan docker compose up -d lagi di terminal pertama. Jika shell Anda juga mengatur ANTHROPIC_API_KEY, Compose menggunakan nilai dari shell, jadi jalankan unset ANTHROPIC_API_KEY terlebih dahulu.
  • database: Database menolak login server, misalnya karena kata sandi salah, atau koneksi terbuka ke database terputus. Untuk mengetahui penyebabnya, jalankan docker compose logs -f cma-server lagi.
• Agen membalas tetapi panggilan alatnya tidak pernah selesai: Tidak ada worker yang melakukan polling ke environment. Periksa log worker dengan docker compose logs sandbox. Worker yang tidak dapat menjangkau socket daemon Docker keluar dengan pesan yang menyebutkan CMA_DOCKER_SOCKET. Atur variabel tersebut di .env ke path socket daemon Anda, lalu jalankan docker compose up -d lagi di terminal pertama.
• Worker berjalan, tetapi panggilan alat tetap tidak pernah selesai: Stack menjalankan 10 worker, dan masing-masing menjalankan container dari satu sesi pada satu waktu. Sebuah sesi mengambil satu worker yang kosong saat Anda membuatnya, dan sesi yang tidak pernah menerima pesan mempertahankan worker-nya hingga satu jam. Jika kesepuluh worker sudah terpakai, panggilan alat dari sesi lain menunggu worker. Jika perintah docker ps pada langkah “Temukan container sandbox” menampilkan 10 container, arsipkan sesi yang tidak Anda gunakan:
  1. Di terminal pertama, jalankan docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}'. Perintah ini mencetak ID sesi di balik setiap container. Sesi yang sedang menunggu belum memiliki container, jadi sesi tersebut tidak ada di daftar.
  2. Di terminal kedua, tekan Ctrl+C untuk keluar dari obrolan, lalu jalankan ant beta:sessions archive --session-id <session-id> untuk setiap sesi dalam daftar yang tidak Anda gunakan.
  3. Jalankan ant beta:sessions connect "$SESSION_ID" lagi. Panggilan alat selesai ketika sebuah worker mengambil sesinya.

Langkah selanjutnya