Definisikan agen Anda

Agen adalah konfigurasi yang dapat digunakan kembali dan memiliki versi yang mendefinisikan persona dan kemampuan. Agen menggabungkan model, "system prompt" (prompt sistem), alat, server MCP, dan skill yang membentuk bagaimana Claude berperilaku selama sesi.

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

Field 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 keseluruhan, sehingga effort milik agen tidak ikut terbawa. Untuk menjalankan sesi pada tingkat effort tertentu, atur effort di dalam objek model pada penimpaan tersebut. Lihat Menimpa konfigurasi agen untuk sesi.

Membuat agen

Contoh berikut mendefinisikan agen coding yang menggunakan Claude Opus 5 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 mencakup 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 field id, type, version, created_at, updated_at, dan archived_at, serta mengisi field model yang Anda hilangkan, seperti effort, dengan nilai defaultnya. 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": "high" },
    "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 defaultnya, always_allow, yang berlaku kecuali Anda mengonfigurasinya.

Menyematkan inference geo

Seperti speed dan effort, inference_geo ditetapkan melalui bentuk objek dari model: teruskan model sebagai objek dan tetapkan inference_geo bersama id. Field ini menerima "us" atau "global". Ketika tidak ditetapkan, setiap permintaan model mengikuti inference geo 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 ketika agen disimpan, ketika sesi dibuat darinya, dan pada setiap giliran yang dilayani sesi. Jika allowlist workspace menyempit sehingga penyematan tidak lagi diizinkan, sesi baru tidak dapat dibuat dari agen tersebut dan sesi yang sedang berjalan menolak giliran selanjutnya; penyematan tidak pernah dikecualikan, karena workspace mengandalkannya untuk kepatuhan dan residensi data.

Menetapkan inference_geo pada model yang tidak mendukung penyematan inferensi geografis mengembalikan error 400; lihat Ketersediaan model untuk model yang mendukungnya. Dalam konfigurasi multiagent, penyematan koordinator dan setiap anggota roster harus semuanya ditetapkan ke nilai yang sama atau semuanya tidak ditetapkan; lihat Orkestrasi multiagen. Untuk mengubah atau menghapus penyematan nanti, perbarui objek model agen; menyediakan model tanpa inference_geo akan menghapusnya, seperti dijelaskan di bawah Semantik pembaruan.

Memperbarui agen

Memperbarui agen menghasilkan versi baru ketika konfigurasi berubah. Field version bersifat opsional: sediakan untuk optimistic concurrency (ketidakcocokan mengembalikan 409), atau hilangkan untuk menerapkan pembaruan tanpa syarat (penulisan terakhir menang). Pembaruan pada agen yang diarsipkan ditolak.

Dengan CLI, edit file agen dan jalankan ant apply lagi; apply akan 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 menyediakan 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:

updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
  -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 '{
    "description": "Writes and reviews code."
  }')

echo "New version: $(jq -r '.version' <<< "$updated_agent")"

Semantik pembaruan

• version bersifat opsional dan harus minimal 1 ketika disediakan. Ketika disediakan, permintaan mengembalikan 409 jika tidak cocok dengan versi agen saat ini, bahkan ketika field yang Anda kirim sudah cocok dengan nilai yang tersimpan; baca ulang agen dan coba lagi. Ketika dihilangkan, pembaruan diterapkan tanpa syarat dan pembaruan terbaru secara diam-diam menggantikan pembaruan bersamaan lainnya, tanpa error bagi kedua pemanggil. Menyediakan 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.

• Field yang dihilangkan dipertahankan. Anda hanya perlu menyertakan field yang ingin Anda ubah.

• Field skalar (model, system, name, description) diganti dengan nilai baru. system dan description dapat dihapus dengan meneruskan null. model dan name bersifat wajib dan tidak dapat dihapus. Di dalam objek model yang Anda sediakan, effort adalah satu-satunya pengecualian: jika id model tidak berubah, menghilangkan effort membiarkan tingkat effort yang tersimpan tidak berubah. Jika Anda mengubah id model, effort yang dihilangkan direset ke default model baru. Field model lainnya diganti bersama objeknya: menyediakan model tanpa inference_geo menghapus penyematan inference geo agen.

• Field array (tools, mcp_servers, skills) diganti sepenuhnya oleh array baru. Untuk menghapus field array seluruhnya, teruskan null atau array kosong.

• multiagent diganti secara keseluruhan, termasuk roster agents-nya. Teruskan null untuk menghapusnya.

• Metadata digabungkan pada tingkat key. Key yang Anda sediakan ditambahkan atau diperbarui. Key yang Anda hilangkan dipertahankan. Untuk menghapus key tertentu, tetapkan 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.

• Roster koordinator tidak diperbarui. Koordinator yang mereferensikan agen ini dalam roster multiagent.agents mereka tetap menggunakan versi yang disematkan ketika koordinator dibuat atau terakhir diperbarui, bahkan jika referensi tersebut menghilangkan version. Untuk mendelegasikan ke versi baru, perbarui koordinator agar rosternya mereferensikannya.

Siklus hidup agen

Daftar versi

Ambil riwayat versi lengkap untuk melacak bagaimana agen telah 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()}")

Mengarsipkan agen

Pengarsipan membuat agen menjadi read-only dan tidak dapat dibatalkan. Sesi yang ada terus berjalan, tetapi sesi baru tidak dapat mereferensikan agen tersebut. Respons menetapkan archived_at ke timestamp pengarsipan.

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

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

Langkah selanjutnya