Mulai sesi

Sesi adalah instans agen yang sedang berjalan dalam sebuah lingkungan. Setiap sesi mereferensikan sebuah agen dan sebuah lingkungan (keduanya dibuat secara terpisah), dan mempertahankan riwayat percakapan di berbagai interaksi.

Semua permintaan API Managed Agents memerlukan header beta managed-agents-2026-04-01. SDK menetapkan header beta secara otomatis.

Membuat sesi

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

session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID"
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")

Untuk menyematkan sesi ke versi agen tertentu, masukkan sebuah objek. Ini memungkinkan Anda mengontrol versi mana yang berjalan dan melakukan peluncuran bertahap versi baru secara independen.

Agen mendefinisikan bagaimana Claude berperilaku dalam sesi, termasuk model, system prompt, alat, dan server MCP. Lihat Pengaturan agen untuk detailnya.

Autentikasi MCP melalui vault

Jika agen Anda menggunakan alat MCP yang memerlukan autentikasi, masukkan vault_ids saat pembuatan sesi untuk mereferensikan vault yang berisi kredensial OAuth yang tersimpan. Anthropic mengelola pembaruan token atas nama Anda. Lihat Autentikasi dengan vault untuk cara membuat vault dan mendaftarkan kredensial.

Memulai sesi

Membuat sesi menyediakan lingkungan dan agen tetapi tidak memulai pekerjaan apa pun. Untuk mendelegasikan tugas, kirim event ke sesi menggunakan user event. Sesi bertindak sebagai mesin status yang melacak kemajuan sementara event mendorong eksekusi yang sebenarnya.

Lihat Event dan streaming untuk cara melakukan streaming respons agen dan menangani konfirmasi alat.

Status sesi

Sesi berkembang melalui status-status berikut:

Status	Deskripsi
`idle`	Agen sedang menunggu input, termasuk pesan pengguna atau konfirmasi alat. Sesi dimulai dalam status `idle`.
`running`	Agen sedang aktif mengeksekusi
`rescheduling`	Terjadi kesalahan sementara, mencoba ulang secara otomatis
`terminated`	Sesi telah berakhir karena kesalahan yang tidak dapat dipulihkan

Operasi sesi lainnya

Mengambil sesi

Mendaftar sesi

Mengarsipkan sesi

Arsipkan sesi untuk mencegah event baru dikirim sambil mempertahankan riwayatnya:

Menghapus sesi

Hapus sesi untuk menghapus catatan, event, dan kontainer terkaitnya secara permanen. Sesi yang sedang running tidak dapat dihapus; kirim interrupt event jika Anda perlu menghapusnya segera.

File, penyimpanan memori, lingkungan, dan agen adalah sumber daya independen dan tidak terpengaruh oleh penghapusan sesi.

pinned_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": {"type": "agent", "id": "$AGENT_ID", "version": 1},
  "environment_id": "$ENVIRONMENT_ID"
}
EOF
)
PINNED_SESSION_ID=$(jq -r '.id' <<< "$pinned_session")

vault_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "vault_ids": ["$VAULT_ID"]
}
EOF
)
VAULT_SESSION_ID=$(jq -r '.id' <<< "$vault_session")

curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "events": [
    {
      "type": "user.message",
      "content": [{"type": "text", "text": "List the files in the working directory."}]
    }
  ]
}
EOF

retrieved=$(curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")
echo "Status: $(jq -r '.status' <<< "$retrieved")"

curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "\(.id): \(.status)"'

curl -fsSL -X POST "https://api.anthropic.com/v1/sessions/$SESSION_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

curl -fsSL -X DELETE "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"