Memanggil API pada server yang di-host sendiri

Server Claude Managed Agents yang di-host sendiri memiliki API yang sama dengan layanan Managed Agents yang di-hosting oleh Anthropic. Kode Anda memanggilnya dengan SDK resmi, cURL, atau CLI ant. Ada dua hal yang berubah: “base URL” (URL dasar) adalah alamat server Anda, dan kunci API adalah kunci API server Anda, bukan kunci API Claude.

Untuk membuat agen dan menjalankan sesi di browser, lihat Gunakan konsol di server Anda.

Prasyarat

• Server yang berjalan: Mulai satu server dengan Memulai dengan Claude Managed Agents yang di-host sendiri atau Menerapkan di Kubernetes.
• Akses ke server: Jika orang lain yang menjalankan server, tanyakan kepada mereka alamat server dan cara melakukan autentikasi. Jika mereka menggunakan single sign-on, lihat Mengizinkan developer login dari terminal.
• CLI ant: Instal versi terbaru, seperti yang ditunjukkan di quickstart CLI.

Mengarahkan klien Anda ke server Anda

SDK dan CLI ant membaca alamat server dari ANTHROPIC_BASE_URL dan kunci API dari ANTHROPIC_API_KEY. Atur kedua variabel tersebut di terminal yang Anda gunakan khusus untuk server ini.

Untuk stack quickstart, jalankan perintah berikut dari direktori yang berisi file .env Anda:

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

Di Kubernetes, atur kedua variabel tersebut seperti yang ditunjukkan di Menjalankan sesi, dan biarkan port-forward-nya tetap berjalan.

Di terminal tersebut, setiap perintah ant, seperti ant beta:agents list, menjangkau server Anda. Jangan jalankan Claude Code atau docker compose di terminal tersebut, karena keduanya membaca variabel yang sama.

Memulai sesi

Sebuah sesi memerlukan ID agen dan ID lingkungan:

• Agen: Buat satu seperti yang ditunjukkan di Membuat agen, dengan klien Anda diarahkan ke server Anda. Jika Anda mengirim permintaan HTTP mentah, ganti https://api.anthropic.com di URL dengan $ANTHROPIC_BASE_URL.
• Lingkungan: Stack quickstart membuat satu environment bernama compose-sandbox, dan Helm chart membuat satu environment bernama default. ant beta:environments list mencetak nama dan ID setiap environment. Untuk worker Anda sendiri, ID tersebut adalah ID yang dicetak oleh CLI admin di Menjalankan worker Anda sendiri.

Masukkan kedua ID Anda ke shell Anda, sebagai pengganti ID contoh berikut:

export AGENT_ID=agent_011CYm1BLqPXpQRk5khsSXrs
export ENVIRONMENT_ID=env_01595EKxaaTTGwwY3kyXdtbs

Contoh berikut membuat sesi dan mengirim pesan pertamanya dalam permintaan yang sama:

import os

from anthropic import Anthropic

client = Anthropic()

session = client.beta.sessions.create(
    agent=os.environ["AGENT_ID"],
    environment_id=os.environ["ENVIRONMENT_ID"],
    initial_events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)
print(session.id)

Respons berisi ID sesi, yang diawali dengan sesn_. Agen langsung mulai bekerja. Alat bawaannya, seperti bash, berjalan pada worker yang melayani environment tersebut.

Untuk memantau sesi, buka konsol di server Anda di browser, pilih Sessions, lalu pilih sesi tersebut. Sesi yang Anda mulai dengan kunci API server, seperti di halaman ini, hanya terlihat oleh administrator.

Untuk mengikuti sesi di terminal Anda, teruskan ID-nya ke ant beta:sessions connect:

ant beta:sessions connect sesn_011CZkZAtmR3yMPDzynEDxu7

Untuk hal lain yang dapat dilakukan sesi, seperti menyematkan versi agen, lihat Memulai sesi.

Mengirim pesan dan membaca balasan

Masukkan ID sesi Anda ke shell Anda, sebagai pengganti ID contoh berikut:

export SESSION_ID=sesn_011CZkZAtmR3yMPDzynEDxu7

Tunggu hingga sesi dalam keadaan idle sebelum Anda menjalankan contoh berikutnya. Contoh tersebut berhenti membaca ketika sebuah giliran berakhir. Jika giliran sebelumnya masih berjalan, akhir giliran tersebut dapat menghentikan contoh sebelum balasan untuk pesan Anda tiba. Konsol dan ant beta:sessions connect sama-sama menampilkan status sesi.

Contoh berikut mengirim pesan dan mencetak balasan agen. Contoh ini membuka aliran event sesi terlebih dahulu, karena aliran hanya mengirimkan event yang muncul setelah aliran dibuka:

import os

from anthropic import Anthropic

client = Anthropic()
session_id = os.environ["SESSION_ID"]

with client.beta.sessions.events.stream(session_id) as stream:
    client.beta.sessions.events.send(
        session_id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {"type": "text", "text": "Summarize what you did in one sentence."}
                ],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.error":
                error_message = event.error.message if event.error else "unknown"
                print(f"\n[Error: {error_message}]")
            case "session.status_idle":
                if event.stop_reason.type != "requires_action":
                    break
            case "session.status_terminated":
                break

Selain mencetak teks agent.message, loop menangani tiga event:

• session.status_idle: Loop berakhir, kecuali stop_reason.type milik event tersebut adalah requires_action.
• session.status_terminated: Loop berakhir.
• session.error: Loop mencetak pesan error tersebut dan terus membaca, karena server dapat mencoba ulang panggilan model yang gagal dan menyelesaikan giliran tersebut.

requires_action berarti sesi dijeda untuk panggilan alat. Apa yang mengakhiri jeda tersebut bergantung pada panggilannya:

• Panggilan alat kustom, atau permintaan untuk mengonfirmasi panggilan alat: Hanya kode Anda yang dapat menjawabnya. Jika agen Anda menggunakan salah satunya, lihat Menjawab panggilan alat yang menjeda sesi.
• Panggilan ke alat yang dijalankan oleh worker, seperti bash: Panggilan ini biasanya tidak menjeda sesi. Jika tidak ada worker yang mengambil panggilan tersebut selama sekitar 3 menit, sesi dijeda hingga sebuah worker mengembalikan hasilnya. Dalam kasus tersebut, kode Anda tidak perlu menjawab apa pun. Biarkan aliran tetap terbuka, dan giliran akan berlanjut ketika worker menjalankan panggilan tersebut.

Untuk event lain yang dikirim sesi, dan cara menyambung ulang tanpa melewatkan satu pun, lihat Aliran event sesi.

Memindahkan data masuk dan keluar dari sesi

Data masuk ke sesi dan keluar darinya melalui direktori kerja worker.

Pada stack quickstart, container setiap sesi dimulai dengan direktori /workspace yang kosong, kecuali clone dari repositori sesi tersebut. Secara default, sekitar satu menit setelah sebuah giliran berakhir, container berhenti, dan Docker menghapusnya bersama direktori tersebut. Apa pun yang harus disimpan oleh sesi harus dikeluarkan melalui pemanggilan alat, seperti unggahan atau git push, sebelum itu terjadi.

Container juga berhenti sekitar satu jam setelah dimulai, bahkan di tengah sebuah giliran. Tidak ada pengaturan yang mengubah hal tersebut. Giliran berlanjut di container baru, biasanya setelah satu atau dua menit, dan klien Anda tidak menerima event apa pun untuk peralihan tersebut. Peralihan ini memiliki dua konsekuensi:

• Perintah: Semua yang berjalan di container lama berhenti. Container baru menjalankan ulang panggilan alat yang terputus dari awal, tetapi tidak ada yang memulai ulang perintah yang dibiarkan agen berjalan di latar belakang.
• File: Direktori /workspace milik container baru kembali kosong, kecuali clone baru dari repositori sesi tersebut.

Dalam giliran yang panjang, minta agen mengunggah atau melakukan push atas pekerjaannya secara bertahap, dan hindari perintah yang menimbulkan masalah jika dijalankan dua kali.

Di Kubernetes, sebuah sesi mempertahankan satu pod paling lama sekitar satu jam, dan giliran berlanjut dengan cara yang sama. Ada dua hal yang berbeda: pod baru menemukan file sesi di /workspace, dan pod tersebut dimulai sekitar 6 menit setelah pod lama berhenti.

Untuk worker yang Anda mulai sendiri, letakkan file input di direktori kerja sebelum Anda mengirim pesan yang membutuhkannya. Baca file output darinya setelahnya.

Jika Anda sendiri yang memulai container untuk setiap sesi, mount direktori yang berisi file input sesi sebagai direktori kerja container. Kumpulkan file output darinya setelah container berhenti. Lihat Menyiapkan file untuk sesi.

Menemukan contoh lainnya di panduan layanan yang di-hosting

Panduan layanan yang di-hosting menjelaskan konsep inti API dan memiliki contoh untuk setiap fitur. Contoh SDK dan CLI pada panduan-panduan tersebut memanggil server Anda saat Anda menjalankannya di terminal tempat ANTHROPIC_BASE_URL dan ANTHROPIC_API_KEY diatur. Contoh cURL pada panduan-panduan tersebut menyebutkan https://api.anthropic.com, jadi ganti alamat tersebut dengan $ANTHROPIC_BASE_URL sebelum Anda menjalankannya.

Untuk beberapa fitur, server Anda memerlukan pengaturan terlebih dahulu, atau sebuah contoh perlu diubah:

Perbedaan dari layanan yang di-hosting berisi daftar lengkapnya. Periksa daftar tersebut sebelum Anda memindahkan aplikasi yang sudah ada.

Menjalankan worker Anda sendiri

Stack quickstart membuat environment dan menjalankan worker-nya. Begitu pula Helm chart di Menerapkan di Kubernetes. Jika worker tersebut sudah cukup untuk kebutuhan Anda, lewati bagian ini.

Anda menjalankan worker seperti yang Anda lakukan untuk sandbox yang di-host sendiri: perintah ant beta:worker dan worker SDK yang sama, dengan cara-cara yang ditunjukkan di Menerapkan worker self-hosted. Pengecualiannya adalah worker yang dipicu oleh webhook, karena server Anda tidak mengirimkan webhook apa pun.

Membuat environment dan kuncinya

Buat environment dan kunci environment dengan CLI admin, bukan di Claude Console. CLI tersebut, cma-server-admin, berada di bagian teratas arsip rilis, jadi jalankan perintah dari sana. Untuk -base-url, teruskan alamat yang digunakan worker Anda untuk menjangkau server:

• Worker di mesin yang menjalankan stack quickstart: http://127.0.0.1:8400
• Worker di mesin lain: alamat https dari proxy TLS yang Anda tempatkan di depan server

CLI admin memanggil server di alamat yang sama, jadi jalankan CLI tersebut di mesin yang dapat menjangkau alamat tersebut.

echo "$ANTHROPIC_API_KEY" | ./cma-server-admin bootstrap \
  -base-url http://127.0.0.1:8400 -name my-env -key-file -

Perintah ini mencetak pengaturan worker, perintah yang memulai worker, serta ID dan masa berlaku kunci:

export ANTHROPIC_BASE_URL='http://127.0.0.1:8400'
export ANTHROPIC_ENVIRONMENT_ID='env_...'
export ANTHROPIC_ENVIRONMENT_KEY='sk-ant-oat01-...'
# then: histchars= HISTFILE=/dev/null ant beta:worker poll --workdir /workspace
# key id: 'etok_...'  expires: '...'

Perintah tersebut hanya menampilkan kunci sekali, jadi simpan kunci, ID-nya, dan masa berlakunya di secret manager Anda. Kunci berhenti berfungsi setelah 365 hari. Sebelum itu, ikuti Mengganti kunci environment untuk worker Anda sendiri.

Jauhkan kunci API server dari mesin yang menjalankan worker. Jalankan worker di container atau VM yang tidak menyimpan apa pun yang perlu Anda lindungi. Untuk tugas keamanan Anda lainnya, lihat Tanggung jawab keamanan Anda.

Menjalankan eksperimen lokal

Jalankan ketiga baris export di shell tempat Anda memulai worker. Lalu mulai worker dengan perintah berikut, bukan perintah yang dicetak. Perintah pertama membuat direktori kerja worker, karena worker tidak membuatnya:

mkdir -p "$HOME/cma-workspace" "$HOME/.config/cma"
cat > "$HOME/.config/cma/worker.inputrc" <<'EOF'
$include /etc/inputrc
set disable-completion on
EOF
histchars= HISTFILE=/dev/null INPUTRC="$HOME/.config/cma/worker.inputrc" \
  ant beta:worker poll --workdir "$HOME/cma-workspace"

histchars, INPUTRC, dan HISTFILE menyiapkan shell di balik alat bash milik worker, sehingga shell menjalankan setiap perintah persis seperti yang ditulis oleh agen:

• histchars=: Shell tidak memperlakukan ! sebagai referensi ke riwayat perintahnya.
• INPUTRC: File ini menonaktifkan pelengkapan otomatis, yang jika tidak dinonaktifkan akan menelan setiap karakter tab dalam perintah. Jauhkan file ini dari direktori kerja, tempat alat file milik agen dapat menulis ulang file tersebut.
• HISTFILE=/dev/null: Shell tidak membaca maupun menulis file riwayat.

Jangan gunakan worker ini untuk hal lain. Worker ini menyimpan kunci environment dan menjalankan alat setiap sesi dalam satu proses. Worker ini juga tidak meng-clone repositori milik sebuah sesi. Sesi berjalan tanpa repositori tersebut, dan klien Anda tidak menerima error.

Menjalankan worker di produksi

Untuk keperluan apa pun selain eksperimen lokal, mulai satu container untuk setiap sesi dan jalankan ant beta:worker run di dalamnya, seperti yang ditunjukkan di Menjalankan satu sandbox per sesi. Berikan image-nya apa yang tercantum di Membangun image sandbox Anda sendiri, dan ubah tiga hal dalam penyiapan tersebut:

• Kunci environment: Jangan teruskan ANTHROPIC_ENVIRONMENT_KEY ke dalam container sebuah sesi. Server menerima kunci tersebut untuk setiap sesi di environment, sedangkan container hanya memerlukan akses ke satu sesi.
• Secret milik work item: Teruskan secret ini sebagai pengganti kunci tersebut, karena server menerimanya hanya untuk satu sesi itu. Meneruskan secret item pekerjaan menunjukkan tempat kode Anda menerimanya. Di tempat bagian tersebut mengatur ANTHROPIC_WORK_SECRET, letakkan secret tersebut dalam file yang hanya dapat dibaca oleh pengguna container. Misalnya, salurkan secret tersebut ke input standar container, dan minta container menulis file tersebut sebelum memulai worker. Lalu atur ANTHROPIC_WORK_SECRET_FILE ke path file tersebut.
• Alamat server: Atur ANTHROPIC_BASE_URL ke alamat yang dapat dijangkau container. http://127.0.0.1:8400 bukan salah satunya.

Untuk worker SDK, dua hal lagi berlaku:

• Versi: Bangun worker pada versi terbaru SDK, seperti yang dijelaskan di SDK, CLI, dan library. Worker pada versi tersebut menunggu persetujuan sebelum menjalankan panggilan alat yang memerlukannya, dan tidak pernah menjalankan panggilan yang ditolak oleh kebijakan. Worker yang dibangun pada versi lama menjalankan setiap panggilan alat segera setelah panggilan tersebut tiba.
• Contoh: Contoh di Menjalankan worker SDK di dalam sandbox membaca kunci environment, sehingga contoh tersebut tidak berfungsi di sini apa adanya.

Membangun image sandbox Anda sendiri

Image milik Anda sendiri memerlukan paket dan pengaturan berikut:

• Paket: Git 2.38 atau yang lebih baru, curl, jq, dan ripgrep, yang digunakan oleh alat grep milik worker untuk melakukan pencarian.

• Pengaturan shell: histchars, HISTFILE, dan INPUTRC, seperti pada eksperimen lokal, serta TERMINFO. Letakkan baris-baris berikut di Dockerfile, sebelum baris USER mana pun:

  ENV histchars=
  RUN printf '\nset disable-completion on\n' >> /etc/inputrc
  ENV INPUTRC=/etc/inputrc TERMINFO=/etc/terminfo HISTFILE=/dev/null
  RUN test -r /etc/terminfo/d/dumb

  

  TERMINFO harus menyebutkan direktori yang berisi d/dumb, deskripsi terminal yang dibaca oleh bash milik worker. Di Alpine dengan bash terinstal, direktori tersebut adalah /etc/terminfo, seperti yang ditunjukkan. Pada base lain, seperti Debian atau Ubuntu, direktori tersebut adalah /lib/terminfo atau /usr/share/terminfo, mana pun yang berisi d/dumb. Tuliskan direktori tersebut di pengaturan TERMINFO dan di baris RUN test, yang menghentikan build jika file tersebut tidak ada.

Image tersebut juga memerlukan dua skrip dari arsip, yang berjalan sebelum worker dimulai:

1. Salin image-build/with-repositories.sh ke /usr/local/bin/cma-with-repositories. Skrip ini meng-clone repositori milik satu sesi.
2. Salin image-build/with-egress.sh ke /usr/local/bin/cma-with-egress. Skrip ini mengarahkan alat sesi ke egress gateway, jika server Anda menjalankannya.
3. Jadikan kedua file tersebut dapat dieksekusi.
4. Letakkan keduanya di depan perintah worker, seperti pada cma-with-egress cma-with-repositories ant beta:worker run .... Lewati langkah ini jika image Anda menjalankan kubernetes/sandbox/worker.sh dari arsip, karena skrip tersebut memulai worker dengan cara ini.

Worker yang dimulai tanpa cma-with-repositories menjalankan sesi tanpa repositori. Klien Anda tidak menerima error.

Memindahkan worker dari layanan yang di-hosting

Jika Anda sudah menjalankan worker untuk layanan yang di-hosting oleh Anthropic, worker yang sama dapat melayani server Anda sebagai gantinya. Lakukan tiga hal:

• Berikan ketiga nilai export yang dicetak oleh CLI admin kepada proses yang melakukan polling untuk pekerjaan.
• Mulai proses tersebut dengan histchars, HISTFILE, dan INPUTRC yang diatur, seperti pada eksperimen lokal.
• Lakukan perubahan yang dijelaskan di Menjalankan worker di produksi, dan periksa image setiap sesi berdasarkan Membangun image sandbox Anda sendiri.

Langkah selanjutnya

• Mengizinkan developer login dari terminal: Siapkan single sign-on, sehingga developer dapat menggunakan CLI ant dengan identitas mereka sendiri, di terminal tanpa ANTHROPIC_API_KEY.
• Identitas dan kredensial agen: Izinkan sistem luar memercayai agen Anda, dan simpan kredensial vault di pengelola rahasia Anda.
• Penyedia inferensi: Kirim panggilan model ke penyedia cloud atau gateway model Anda sendiri.