Memulai sesi
Buat sesi untuk menjalankan agen Anda dan mulai menjalankan tugas.
Sesi adalah instans agen di dalam sebuah lingkungan. Setiap sesi mereferensikan sebuah agen dan sebuah lingkungan (keduanya dibuat secara terpisah), serta mempertahankan riwayat percakapan di berbagai interaksi. Sesi mengikuti siklus hidup dua langkah: pertama buat sesi, lalu kirim event pengguna untuk memulai pekerjaan. Anda juga dapat menggabungkan kedua langkah tersebut menjadi satu panggilan dengan initial_events.
Membuat sesi
Sebuah sesi memerlukan ID agent dan ID environment. Agen adalah sumber daya yang memiliki versi; meneruskan ID agent sebagai string akan membuat sesi dengan versi agen terbaru.
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
)Untuk menyematkan sesi ke versi agen tertentu, teruskan sebuah objek. Ini memungkinkan Anda mengontrol secara tepat versi mana yang berjalan dan melakukan peluncuran bertahap versi baru secara independen.
pinned_session = client.beta.sessions.create(
agent={"type": "agent", "id": agent.id, "version": 1},
environment_id=environment.id,
)Mengisi sesi dengan event awal
Anda dapat membuat sesi dan memulai pekerjaannya dalam satu panggilan. initial_events adalah array opsional berisi event awal yang dikirim ke sesi saat pembuatan, diproses secara berurutan. Array ini mendukung event user.message dan user.define_outcome, serta menerima maksimal 50 event. Daftar yang tidak kosong akan memulai loop agen dalam panggilan yang sama: sesi dibuat langsung dalam status running, tanpa permintaan lebih lanjut.
Contoh berikut membuat sesi dengan satu user.message di initial_events:
seeded_session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
initial_events=[
{
"type": "user.message",
"content": [
{"type": "text", "text": "List the files in the working directory."}
],
},
],
)
# initial_events tidak digemakan pada respons create; baca kembali
# dari daftar event milik sesi.
for event in client.beta.sessions.events.list(seeded_session.id):
if event.type == "user.message":
for block in event.content:
if block.type == "text":
print(f"Seeded event: {block.text}")initial_events tidak ditampilkan kembali dalam respons pembuatan. Untuk melihat pesan yang diisikan, tampilkan daftar event sesi tersebut.
Tidak ada jenis event lain yang diterima. Event yang merespons giliran agen (user.tool_confirmation, user.tool_result, dan user.custom_tool_result) tidak diterima karena belum ada giliran agen, dan user.interrupt tidak diterima karena tidak ada giliran yang perlu dihentikan. Berbeda dengan initial_events pada deployment terjadwal, initial_events milik sesi tidak menerima system.message.
Setiap event di initial_events divalidasi dan disimpan sebelum respons pembuatan dikembalikan, sesuai urutan daftar, dengan ID yang ditetapkan server, persis seolah-olah Anda mengirimkannya ke endpoint kirim event segera setelah pembuatan. Aturan konten per event juga sama seperti pada endpoint tersebut. Daftar kosong setara dengan menghilangkan field tersebut. Validasi bersifat semua-atau-tidak-sama-sekali: jika ada event yang gagal validasi, seluruh permintaan ditolak dan tidak ada sesi yang dibuat.
Permintaan pembuatan ditolak dalam kasus-kasus berikut:
| Kondisi | Status |
|---|---|
Lebih dari satu event user.define_outcome | 400 |
Event user.define_outcome tanpa rubric | 400 |
Lebih dari 100 blok konten document yang bersumber dari file di seluruh daftar | 400 |
| Body permintaan lebih dari 32 MB | 413 |
Event user.define_outcome di initial_events diterima dengan kondisi yang sama seperti mengirimkannya ke sesi yang sudah ada; lihat Mendefinisikan hasil.
Menimpa konfigurasi agen untuk sebuah sesi
Anda dapat meneruskan agent dalam tiga bentuk: string ID agen, objek versi tersemat (type: "agent"), atau objek override (type: "agent_with_overrides"). Bentuk override mengubah sebagian konfigurasi agen untuk satu sesi. Gunakan bentuk ini untuk mencoba model yang berbeda atau memberikan alat tambahan dalam satu sesi tanpa membuat versi baru agen. Untuk bentuk override, teruskan id agen dan secara opsional version (hilangkan version untuk menggunakan versi terbaru agen). Kemudian sertakan salah satu dari model, system, tools, mcp_servers, atau skills dengan nilai yang harus digunakan sesi.
Setiap field yang dapat ditimpa mengikuti tiga aturan yang sama:
- Hilangkan field: Sesi mewarisi nilai dari versi agen yang direferensikannya.
- Atur field ke
null, atau ke array kosong untuk field berupa daftar: Sesi berjalan dengan field tersebut dikosongkan. Aturan ini berlaku sepenuhnya untuksystemdanskills. Ada tiga pengecualian:modeltidak pernah dapat dikosongkan. Sesi selalu memerlukan model, sehingga menyetelmodelkenullmengembalikan error 400agent_model_required.- Mengosongkan
toolsmengembalikan error 400 ketikaskillsefektif milik sesi tidak kosong, karena skill memerlukan alatread. Jika tidak, menyeteltoolskenullatau ke array kosong akan mengosongkan field tersebut. - Mengosongkan
mcp_serversmengembalikan error 400 ketikatoolsefektif sesi masih berisimcp_toolsetyang mereferensikan salah satu server agen. Timpatoolsdalam permintaan yang sama untuk menghapus entrimcp_toolsettersebut, lalu kosongkanmcp_servers.
- Atur field ke sebuah nilai: Nilai tersebut menggantikan nilai agen secara penuh. Override tidak pernah digabungkan dengan konfigurasi agen, sehingga override
toolsharus mencantumkan setiap alat yang harus dimiliki sesi. Demikian pula, overridemodelmenggantikan objekmodelagen secara penuh, sehinggaeffortmilik agen sendiri tidak terbawa. Untuk menjalankan sesi pada tingkat effort tertentu, atureffortdi dalam objekmodeloverride. Tingkat yang tidak didukung model mengembalikan error 400, dan overridemodeltanpaeffortberjalan pada tingkat effort default model tersebut.
Override hanya berlaku untuk sesi yang Anda buat. Override tidak mengubah sumber daya agen atau membuat versi agen baru, sehingga sesi lain yang mereferensikan agen yang sama tidak terpengaruh.
Dalam respons, objek agent mencerminkan konfigurasi yang digunakan sesi setelah override diterapkan. id dan version-nya tetap mengidentifikasi agen dan versi tempat override diterapkan. Ini memungkinkan Anda melacak sesi kembali ke agen dasarnya.
Contoh berikut memulai sesi yang menimpa model dan mengosongkan prompt sistem:
override_session = client.beta.sessions.create(
agent={
"type": "agent_with_overrides",
"id": agent.id,
"model": {"id": "claude-sonnet-5-5"},
"system": None, # clear the agent's system prompt for this session
},
environment_id=environment.id,
)
# Agen pada respons adalah snapshot terselesaikan dengan override yang diterapkan.
print(f"Model: {override_session.agent.model.id}")
print(f"System: {override_session.agent.system}")Menyematkan geo inferensi untuk sebuah sesi
Karena override model menggantikan objek model agen sepenuhnya, override tersebut juga menetapkan atau menghapus penguncian geografi inferensi model untuk sesi. Override yang menyertakan inference_geo mengunci geografi yang melayani permintaan model sesi. Override yang menghilangkannya akan menghapus penguncian agen, sehingga sesi mengikuti default_inference_geo milik workspace. Nilai yang ditimpa divalidasi terhadap allowed_inference_geos milik workspace saat sesi dibuat.
Contoh berikut memulai sesi dari agen yang modelnya tidak memiliki penyematan geo, dan menyematkan permintaan model sesi ke inferensi AS dengan menyertakan inference_geo dalam override model. Respons menampilkan kembali nilai tersebut di agent.model:
session = client.beta.sessions.create(
agent={
"type": "agent_with_overrides",
"id": agent.id,
# Mengganti `model` agen sepenuhnya: nyatakan ulang `id`, tambahkan `inference_geo` untuk menyematkan.
"model": {"id": "claude-opus-5-5", "inference_geo": "us"},
},
environment_id=environment.id,
)
print(f"Inference geo: {session.agent.model.inference_geo}")Menetapkan anggaran sesi
Untuk membatasi pengeluaran sesi, teruskan objek opsional budget saat Anda membuatnya. Anggaran adalah batas atas mutlak pada biaya daftar sesi: platform menghitung harga semua yang dikonsumsi sesi berdasarkan tarif daftar publik, dan sesi berhenti mengirimkan permintaan model baru setelah total berjalan tersebut mencapai max_list_cost. type anggaran selalu limit. Berikan max_list_cost sebuah amount dan sebuah currency. amount adalah bilangan bulat sen AS yang ditulis sebagai string, misalnya "125" untuk $1,25 USD. API menerima string alih-alih angka sehingga tidak pernah ada pembulatan floating-point yang diterapkan. USD adalah satu-satunya mata uang yang saat ini didukung. Ketika sesi mencapai batas tersebut, sesi dijeda dan menjadi idle dengan alasan berhenti budget_reached. Batas ini diberlakukan di antara permintaan model, sehingga permintaan yang melampauinya diselesaikan terlebih dahulu dan biaya daftar akhir sesi dapat berada sedikit melewati batas. Anggaran hanya dapat dilampirkan saat pembuatan: Anda dapat mengubah atau menghapus anggaran nanti, tetapi Anda tidak dapat menambahkannya ke sesi yang dibuat tanpa anggaran.
Contoh berikut membuat sesi dengan anggaran $1,25 USD:
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
budget={
"type": "limit",
"max_list_cost": {"amount": "125", "currency": "USD"},
},
)
print(session.id, session.budget.max_list_cost.amount) # sesn_01... 125Lihat Anggaran sesi untuk cara kerja penegakan, apa saja yang dihitung dalam biaya daftar, dan bagaimana anggaran berperilaku dalam sesi multiagen.
Autentikasi MCP melalui vault
Jika agen Anda menggunakan alat MCP yang memerlukan autentikasi, teruskan vault_ids saat pembuatan sesi untuk mereferensikan vault yang berisi kredensial OAuth tersimpan. Anthropic mengelola penyegaran token atas nama Anda. Lihat Autentikasi dengan vault untuk cara membuat vault dan mendaftarkan kredensial.
vault_session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
vault_ids=[vault.id],
)Memulai sesi
Membuat sesi tanpa initial_events akan mendaftarkan sesi tetapi tidak memulai pekerjaan apa pun; sandbox environment mulai disiapkan segera setelah sesi dibuat, sehingga panggilan alat pertama tidak perlu menunggunya. Untuk mendelegasikan tugas, kirim event ke sesi menggunakan event pengguna. Untuk menyediakan event pertama dalam permintaan pembuatan, lihat Mengisi sesi dengan event awal. Sesi bertindak sebagai mesin status yang melacak kemajuan, dan event menggerakkan eksekusi yang sebenarnya.
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.message",
"content": [
{"type": "text", "text": "List the files in the working directory."}
],
},
],
)Lihat Aliran event sesi untuk cara melakukan streaming respons agen dan menangani konfirmasi alat.
Lihat Status sesi untuk status-status yang dilalui sebuah sesi.
Langkah selanjutnya
Ambil, daftarkan, perbarui, arsipkan, dan hapus sesi Claude Managed Agents.
Kirim event, lakukan streaming respons, dan interupsi atau arahkan ulang sesi Anda saat sedang berjalan.
Buat dan kelola deployment dengan Claude API: jalankan agen pada jadwal cron berulang dan periksa riwayat eksekusinya.
Apakah halaman ini membantu?