Memulai sesi

Sesi adalah instans agen di dalam sebuah lingkungan. Setiap sesi mereferensikan sebuah agen dan sebuah lingkungan (keduanya dibuat secara terpisah), dan mempertahankan riwayat percakapan di sepanjang beberapa interaksi. Sesi mengikuti siklus hidup dua langkah: pertama buat sesi untuk menyediakan sandbox-nya, lalu kirim user event untuk memulai pekerjaan.



Membuat sesi

Sebuah sesi memerlukan ID agent dan ID environment. Agen adalah sumber daya yang memiliki versi; meneruskan ID agent sebagai string akan memulai sesi dengan versi agen terbaru.

ant 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 dijalankan dan mengatur peluncuran versi baru secara independen.

ant beta:sessions create <<YAML
agent:
  type: agent
  id: $AGENT_ID
  version: 1
environment_id: $ENVIRONMENT_ID
YAML



Menimpa konfigurasi agen untuk sebuah sesi

Anda dapat meneruskan agent dalam tiga bentuk: string ID agen, objek versi tersemat (type: "agent"), atau objek overrides. Bentuk overrides mengubah sebagian konfigurasi agen untuk satu sesi saja. Gunakan ini untuk mencoba model yang berbeda atau memberikan alat tambahan dalam satu sesi tanpa membuat versi baru pada agen. Untuk bentuk overrides, atur type ke agent_with_overrides dan teruskan id agen serta 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 untuk system, mcp_servers, dan skills. Ada dua pengecualian:
  • model tidak pernah dapat dikosongkan. Sebuah sesi selalu membutuhkan model, sehingga model: null mengembalikan error 400 agent_model_required.
  • Mengosongkan tools mengembalikan error 400 ketika skills efektif pada sesi tidak kosong, karena skills memerlukan alat read. Jika tidak, tools: null dan tools: [] akan mengosongkan field tersebut.
• Atur field ke sebuah nilai: Nilai tersebut menggantikan nilai agen secara penuh. Overrides tidak pernah digabungkan dengan konfigurasi agen, sehingga override tools harus mencantumkan setiap alat yang harus dimiliki sesi.

Overrides hanya berlaku untuk sesi yang Anda buat. Overrides tidak memodifikasi 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 dijalankan sesi setelah overrides diterapkan. id dan version-nya tetap mengidentifikasi agen dan versi tempat overrides diterapkan. Ini memungkinkan Anda melacak sesi kembali ke agen dasarnya.

# `agent` pada respons adalah snapshot yang telah di-resolve: setiap override mengganti field
# itu hanya untuk sesi ini, dan resource agent mempertahankan id serta versinya.
ant beta:sessions create \
  --transform 'agent.{id,version,model,system}' \
  --format json <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-sonnet-5
  system: null
environment_id: $ENVIRONMENT_ID
YAML



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 yang tersimpan. Anthropic mengelola penyegaran token atas nama Anda. Lihat Autentikasi dengan vault untuk cara membuat vault dan mendaftarkan kredensial.

ant beta:sessions create <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
vault_ids:
  - $VAULT_ID
YAML



Memulai sesi

Membuat sesi akan menyediakan sandbox lingkungan tetapi tidak memulai pekerjaan apa pun. Untuk mendelegasikan tugas, kirim event ke sesi menggunakan user event. Sesi bertindak sebagai "state machine" (mesin status) yang melacak kemajuan sementara event menggerakkan eksekusi sebenarnya.

ant beta:sessions:events send \
  --session-id "$SESSION_ID" <<'YAML'
events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML

Lihat Aliran event sesi untuk cara melakukan streaming respons agen dan menangani konfirmasi alat.

Lihat Status sesi untuk status-status yang dilalui sebuah sesi, dan Operasi sesi untuk mengambil, mencantumkan, memperbarui, mengarsipkan, dan menghapus sesi.

Untuk membuat sesi secara otomatis pada jadwal berulang, lihat Deployment terjadwal.