Definisikan agen Anda

Agen adalah konfigurasi yang dapat digunakan ulang dan memiliki versi yang mendefinisikan persona dan kemampuan. Agen menggabungkan model, prompt sistem, alat, server MCP, dan skill yang membentuk perilaku Claude selama sesi.

Buat agen sekali sebagai sumber daya yang dapat digunakan ulang dan rujuk agen tersebut berdasarkan ID setiap kali Anda memulai sesi. Agen memiliki versi dan lebih mudah dikelola di banyak sesi.

Bidang konfigurasi agen

Anda juga dapat menimpa model, system, tools, mcp_servers, dan skills untuk satu sesi tanpa mengubah agen. Penimpaan model menggantikan objek model milik agen secara penuh, sehingga effort milik agen sendiri tidak terbawa. Untuk menjalankan sesi pada tingkat effort tertentu, atur effort di dalam objek model penimpaan tersebut. Lihat Menimpa konfigurasi agen untuk sesi.

Buat agen

Contoh berikut mendefinisikan agen coding yang menggunakan model Claude Opus terbaru dengan akses ke toolset agen bawaan. Toolset ini memungkinkan agen menulis kode, membaca file, mencari di web, dan lainnya. Lihat referensi alat agen untuk daftar lengkap alat yang didukung.

Contoh-contoh ini menggunakan curl, CLI ant, atau salah satu SDK. Jika Anda belum menyiapkannya, quickstart membahas instalasi dan penyiapan klien.

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent.

Respons menggemakan konfigurasi Anda dan menambahkan bidang id, type, version, created_at, updated_at, dan archived_at, serta mengisi bidang model yang Anda hilangkan, seperti effort, dengan nilai default-nya. version dimulai dari 1 dan bertambah setiap kali pembaruan mengubah agen.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-5-5",
    "effort": { "type": "medium" },
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "skills": [],
  "mcp_servers": [],
  "multiagent": null,
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

default_config pada toolset menunjukkan kebijakan izin default-nya, always_allow, yang berlaku kecuali Anda mengonfigurasinya.

Sematkan geo inferensi

Seperti speed dan effort, inference_geo diatur melalui bentuk objek dari model: berikan model sebagai objek dan atur inference_geo bersama id. Bidang ini menerima "us" atau "global". Jika tidak diatur, setiap permintaan model mengikuti geo inferensi default workspace pada saat permintaan dilayani. Lihat Residensi data untuk kontrol geo tingkat workspace dan harga.

Contoh berikut menyematkan agen ke inferensi AS dan mencetak nilai inference_geo dari objek model milik agen:

ant apply geo-pinned-assistant.md

---
name: Geo-pinned assistant
model:
  id: claude-opus-5-5
  inference_geo: us
---

You are a helpful assistant.

Penyematan inference_geo divalidasi terhadap allowed_inference_geos milik workspace saat agen disimpan, saat sesi dibuat darinya, dan pada setiap giliran yang dilayani sesi. Jika daftar izin workspace dipersempit sehingga suatu penyematan tidak lagi diizinkan, sesi baru tidak dapat dibuat dari agen tersebut dan sesi yang sedang berjalan menolak giliran berikutnya; penyematan tidak pernah dikecualikan, karena workspace mengandalkannya untuk kepatuhan dan residensi data.

Mengatur inference_geo pada model yang tidak mendukung penyematan inferensi geografis akan mengembalikan error 400; lihat Ketersediaan model untuk model yang mendukungnya. Dalam konfigurasi multiagent, penyematan agen dan penyematan setiap agen yang tercantum dalam daftar predefined_agents dari subagents atau workflows harus semuanya diatur ke nilai yang sama atau semuanya tidak diatur; lihat Orkestrasi multiagen. Untuk mengubah atau menghapus penyematan nanti, perbarui objek model milik agen; memberikan model tanpa inference_geo akan menghapusnya, seperti dijelaskan di bawah Semantik pembaruan.

Perbarui agen

Memperbarui agen menghasilkan versi baru ketika konfigurasi berubah. Bidang version bersifat opsional: berikan untuk konkurensi optimistis (ketidakcocokan mengembalikan 409), atau hilangkan untuk menerapkan pembaruan tanpa syarat (penulisan terakhir yang menang). Pembaruan pada agen yang diarsipkan akan ditolak.

Dengan CLI, edit file agen dan jalankan ant apply lagi; apply memberikan version untuk Anda.

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent. Always write tests.

Contoh sebelumnya memberikan version dari respons pembuatan, sehingga pembaruan hanya diterapkan jika tidak ada hal lain yang mengubah agen sejak Anda membacanya. Untuk menerapkan pembaruan tanpa syarat, hilangkan version dari permintaan:

unconditional_agent = client.beta.agents.update(
    agent.id,
    description="Writes and reviews code.",
)

print(f"New version: {unconditional_agent.version}")

Semantik pembaruan

• version bersifat opsional dan harus minimal 1 jika diberikan. Jika diberikan, permintaan mengembalikan 409 jika tidak cocok dengan versi agen saat ini, bahkan ketika bidang yang Anda kirim sudah cocok dengan nilai yang tersimpan; baca ulang agen dan coba lagi. Jika dihilangkan, pembaruan diterapkan tanpa syarat dan pembaruan terbaru secara diam-diam menggantikan pembaruan bersamaan lainnya, tanpa error bagi pemanggil mana pun. Memberikan version adalah default yang direkomendasikan untuk pemanggil interaktif, dan menghilangkannya cocok untuk loop apply deklaratif, seperti job CI yang menyinkronkan definisi agen yang di-check-in, di mana loop tersebut memiliki agen.

• Bidang yang dihilangkan dipertahankan. Anda hanya perlu menyertakan bidang yang ingin Anda ubah.

• Bidang skalar (model, system, name, description) diganti dengan nilai baru. system dan description dapat dihapus dengan memberikan None. model dan name bersifat wajib dan tidak dapat dihapus. Di dalam objek model yang Anda berikan, effort adalah satu-satunya pengecualian: jika id model tidak berubah, menghilangkan effort membuat tingkat effort yang tersimpan tidak berubah. Jika Anda mengubah id model, effort yang dihilangkan akan direset ke default model baru. Bidang model lainnya diganti bersama objeknya: memberikan model tanpa inference_geo akan menghapus penyematan geo inferensi agen.

• Bidang array (tools, mcp_servers, skills) sepenuhnya diganti oleh array baru. Untuk menghapus bidang array sepenuhnya, berikan None atau array kosong.

• multiagent digabungkan ke dalam blok yang tersimpan tingkat demi tingkat ketika pembaruan mempertahankan tipe multiagent_20261001. Pengaturan yang Anda hilangkan mempertahankan nilai tersimpannya, dan daftar predefined_agents yang Anda kirim menggantikan daftar yang tersimpan. Pembaruan lain apa pun yang mengirim multiagent menggantikan blok yang tersimpan secara keseluruhan, dan pengaturan yang dihilangkannya mengambil nilai default. Berikan multiagent=None untuk menghapus seluruh blok. Di dalam blok, null mereset pengaturan ke default-nya, sehingga mengatur workflows ke null akan mengaktifkan alur kerja dinamis. Lihat Aktifkan alur kerja dinamis.

• Metadata digabungkan pada tingkat kunci. Kunci yang Anda berikan ditambahkan atau diperbarui. Kunci yang Anda hilangkan dipertahankan. Untuk menghapus kunci tertentu, atur nilainya ke null.

• Deteksi no-op. Jika pembaruan tidak menghasilkan perubahan relatif terhadap versi saat ini, tidak ada versi baru yang dibuat dan versi yang ada dikembalikan.

• Daftar predefined_agents milik agen lain tidak diperbarui. Agen yang mencantumkan agen ini dalam daftar predefined_agents dari subagents atau workflows mempertahankan versi yang disematkan saat agen tersebut dibuat atau saat pembaruan terakhir mengirim daftar itu, bahkan jika referensinya menghilangkan version. Untuk mendelegasikan ke versi baru, perbarui agen yang mencantumkannya sehingga daftar tersebut merujuk ke versi baru.

Pembaruan berikut menghapus deskripsi, menghapus kunci team dari metadata, dan mengatur workflows ke null, yang mengaktifkan alur kerja dinamis:

ant apply code-reviewer.md

---
name: Code Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
metadata:
  owner: docs
multiagent:
  type: multiagent_20261001
  workflows: null
---

You are a helpful coding agent.

Siklus hidup agen

Daftar versi

Ambil riwayat versi lengkap untuk melacak bagaimana agen berubah dari waktu ke waktu. Hasil dipaginasi, dan contoh SDK mengambil setiap halaman secara otomatis.

for version in client.beta.agents.versions.list(agent.id):
    print(f"Version {version.version}: {version.updated_at.isoformat()}")

Arsipkan agen

Pengarsipan membuat agen menjadi hanya-baca dan tidak dapat dibatalkan. Sesi yang ada tetap berjalan, tetapi sesi baru tidak dapat merujuk agen tersebut. Respons mengatur archived_at ke timestamp pengarsipan.

archived = client.beta.agents.archive(agent.id)

print(f"Archived at: {archived.archived_at.isoformat()}")

Langkah selanjutnya