Alat

Claude Managed Agents menyediakan serangkaian alat bawaan yang dapat digunakan Claude secara otonom di dalam sebuah sesi. Anda mengontrol alat mana yang tersedia dengan menentukannya dalam konfigurasi agen.

Claude Managed Agents juga mendukung alat kustom yang didefinisikan pengguna. Aplikasi Anda mengeksekusi alat-alat ini secara terpisah dan mengembalikan hasilnya ke Claude, yang menggunakannya untuk melanjutkan tugas. Untuk memberi agen alat dari server MCP, gunakan konektor MCP sebagai gantinya.



Alat yang tersedia

Toolset agen mencakup alat-alat berikut. Semuanya diaktifkan secara default saat Anda menyertakan toolset dalam konfigurasi agen Anda. Setiap entri dalam array configs diidentifikasi berdasarkan name-nya, menggunakan nilai pada kolom Nama, dan menerima field type opsional dengan nilai yang sama. Entri web_search dan web_fetch menerima pengaturan tambahan; lihat Membatasi domain web search dan web fetch.

Ketika output alat melebihi 100.000 karakter (sekitar 25.000 token), output tersebut secara otomatis ditulis ke file di sandbox. Model menerima pratinjau terpotong beserta path file dan dapat membaca konten lengkapnya dari sana.



Mengonfigurasi toolset

Aktifkan toolset lengkap dengan agent_toolset_20260401 saat membuat agen. Gunakan array configs untuk menonaktifkan alat tertentu atau menimpa pengaturannya. Setiap entri config juga dapat menetapkan permission_policy yang mengontrol apakah panggilan alat tersebut disetujui otomatis atau memerlukan konfirmasi. Lihat Kebijakan izin untuk jenis kebijakan yang tersedia.

Entri config untuk web_search dan web_fetch juga menerima filter domain dan pengaturan web lainnya; lihat Membatasi domain web search dan web fetch.

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
YAML



Menonaktifkan alat tertentu

Untuk menonaktifkan sebuah alat, tetapkan enabled: false pada entri config-nya di objek toolset dalam array tools agen Anda:

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}



Mengaktifkan hanya alat tertentu

Objek default_config menetapkan baseline untuk setiap alat dalam set, dan entri configs per alat menimpanya. Untuk memulai dengan semuanya nonaktif dan hanya mengaktifkan yang Anda butuhkan, tetapkan default_config.enabled ke false:

{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash", "enabled": true },
    { "name": "read", "enabled": true },
    { "name": "write", "enabled": true }
  ]
}



Membatasi domain web search dan web fetch

Untuk mengontrol situs mana yang dapat dijangkau oleh alat web agen, tetapkan allowed_domains (alat hanya dapat menjangkau host ini) atau blocked_domains (alat tidak pernah dapat menjangkau host ini) pada entri web_search dan web_fetch dalam array configs toolset. Setiap alat memiliki daftarnya sendiri, sehingga web_search dan web_fetch dapat memiliki pembatasan yang berbeda. Domain yang terdaftar mencakup host tersebut dan semua subdomainnya. Saat runtime, panggilan web_fetch untuk URL yang tidak diizinkan oleh daftarnya mengembalikan hasil error ke agen (is_error: true pada event agent.tool_result, dengan konten yang menyebutkan kode error url_not_allowed), dan web_search menghilangkan hasil yang tidak diizinkan oleh daftarnya.

Toolset berikut membatasi web_search ke dua situs dan melokalkan hasilnya, serta memblokir satu host untuk web_fetch sambil membatasi seberapa banyak konten yang diambil masuk ke dalam konteks:

{
  "type": "agent_toolset_20260401",
  "configs": [
    {
      "type": "web_search",
      "name": "web_search",
      "allowed_domains": ["docs.example.com", "arxiv.org"],
      "user_location": {
        "type": "approximate",
        "country": "US",
        "timezone": "America/Los_Angeles"
      }
    },
    {
      "type": "web_fetch",
      "name": "web_fetch",
      "blocked_domains": ["ads.example.com"],
      "max_content_tokens": 50000
    }
  ]
}

Permintaan berikut membuat agen dengan toolset ini dan mencetak array configs dari respons:

ant beta:agents create --transform tools.0.configs <<'YAML'
name: Research Agent
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    configs:
      - type: web_search
        name: web_search
        allowed_domains: [docs.example.com, arxiv.org]
        user_location:
          type: approximate
          country: US
          timezone: America/Los_Angeles
      - type: web_fetch
        name: web_fetch
        blocked_domains: [ads.example.com]
        max_content_tokens: 50000
YAML

Di Claude Console, tetapkan domain yang diizinkan atau diblokir dari baris web_search dan web_fetch pada kartu Built-in tools di formulir agen; tetapkan max_content_tokens dan user_location di tampilan Raw dari konfigurasi agen.

Selain enabled dan permission_policy, entri alat web menerima pengaturan berikut:



Aturan daftar domain

• Tetapkan allowed_domains atau blocked_domains pada sebuah entri, bukan keduanya. Entri yang menetapkan keduanya akan ditolak.
• Setiap daftar memuat 1 hingga 64 domain, masing-masing 1 hingga 255 karakter. Daftar kosong ditolak: untuk tidak menerapkan pembatasan, hilangkan field tersebut atau kirim null.
• Setiap domain adalah nama domain yang dapat didaftarkan, atau subdomain darinya, ditulis sebagai hostname biasa: huruf ASCII, angka, tanda hubung, garis bawah, dan titik, tanpa skema, port, kredensial, wildcard, atau spasi, tanpa label yang diawali atau diakhiri tanda hubung, dan tanpa path selain sufiks path web_search opsional yang dijelaskan nanti dalam daftar ini. Gunakan example.com, bukan https://example.com, example.com:443, atau *.example.com. Hostname dibandingkan tanpa memperhatikan huruf besar/kecil, dan satu / di akhir diabaikan.
• Domain yang terdaftar cocok dengan host tersebut dan subdomainnya: example.com mencakup docs.example.com, tetapi docs.example.com tidak mencakup example.com atau api.example.com. Awalan www. adalah subdomain seperti yang lainnya, sehingga www.example.com tidak mencakup example.com; daftarkan domain polos untuk mencakup keduanya.
• Alamat IP tidak diterima dalam bentuk apa pun, baik IPv4, IPv6, dalam kurung siku, maupun singkatan numerik seperti 127.1. Daftarkan nama domain situs sebagai gantinya.
• Top-level domain polos atau sufiks registri seperti com, co.uk, atau gov.uk ditolak, begitu pula nama satu label seperti intranet. Daftarkan domain lengkap seperti example.co.uk.
• localhost dan host yang berakhiran .localhost, .local, .internal, .localdomain, atau .invalid ditolak.
• Gunakan bentuk xn-- (Punycode) untuk nama domain internasional; domain yang mengandung karakter non-ASCII ditolak.
• Domain web_fetch tidak dapat menyertakan path: gunakan example.com, bukan example.com/*. Domain web_search dapat membawa sufiks path seperti example.com/blog, di mana path tidak boleh mengandung spasi, ?, #, atau karakter apa pun dari $ , | ^ !. Utamakan hostname biasa untuk web_search juga, karena penyedia pencarian mencocokkan sufiks path sebagai pola URL, bukan sebagai aturan host yang ketat.
• Domain duplikat dalam satu daftar ditolak. www.example.com dan example.com dihitung sebagai domain yang berbeda; lihat aturan pencocokan sebelumnya untuk mengetahui apa yang dicakup masing-masing.



Kapan pengaturan divalidasi

Pelanggaran format dan batas ditolak dengan 400 invalid_request_error saat Anda membuat agen atau memperbarui agen, dan saat Anda membuat atau memperbarui sesi yang menyediakan tools. Misalnya, pesan untuk entri yang menetapkan kedua daftar mencakup Only one of allowed_domains or blocked_domains may be set., dan pesan untuk daftar kosong mencakup allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null. Pesan untuk domain yang melanggar aturan format menyebutkan daftarnya dan posisi berbasis nol, misalnya allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com".

Permintaan yang sama juga menolak tiga pengaturan yang bergantung pada penyedia pencarian dan pengambilan: domain dalam allowed_domains yang tidak diizinkan untuk diakses oleh crawler Anthropic, user_location.country yang tidak didukung penyedia pencarian (pesannya berakhir dengan user_location.country: not a country the search provider supports), dan user_location.timezone yang bukan nama IANA yang valid. Sesi memeriksa konfigurasi lagi saat pertama kali menginisialisasi alat; jika pengaturan yang sebelumnya diterima tidak lagi valid pada saat itu, sesi memancarkan event session.error dan kembali ke idle tanpa mencoba ulang. Perbaiki pengaturan dengan memperbarui alat sesi, perbarui juga agen agar sesi baru dimulai dengan konfigurasi yang telah diperbaiki, lalu kirim user.message baru untuk melanjutkan.



Sesi multiagen, outcome, dan pembaruan di tengah sesi

Dalam sesi multiagen, setiap daftar domain yang berlaku untuk sebuah thread diberlakukan secara bersamaan: agen dalam roster koordinator terikat oleh allowed_domains dan blocked_domains miliknya sendiri, oleh milik agen mana pun yang memanggilnya, dan oleh daftar koordinator saat ini.

• Allowlist digabungkan menjadi domain yang dicakup oleh semuanya, dan blocklist dijumlahkan, sehingga agen roster dapat mempersempit apa yang dijangkau alat tetapi tidak pernah memperluasnya. Misalnya, agen roster yang menetapkan blocked_domains mempertahankan allowed_domains koordinator dan memblokir host tersebut di dalamnya, dan agen roster yang menetapkan allowed_domains sendiri hanya dapat menjangkau host yang dicakup oleh daftarnya maupun daftar koordinator.
• Jika allowlist gabungan tidak memiliki domain yang sama, alat tetap tersedia bagi agen tersebut tetapi setiap panggilan gagal dengan error url_not_allowed yang menyatakan bahwa tidak ada domain yang diizinkan, dan deskripsi alat memberi tahu model demikian. Jaga agar allowlist setiap agen roster berada di dalam allowlist koordinator untuk menghindari hal ini.
• max_content_tokens dan user_location tidak digabungkan: sebuah thread menggunakan nilai dari konfigurasi alatnya sendiri jika ditetapkan, jika tidak dari agen yang memanggilnya, jika tidak dari konfigurasi koordinator saat ini.
• Entri roster {"type": "self"} tidak memiliki pengaturan web sendiri dan mengikuti pengaturan koordinator saat ini.
• Grader dalam sesi berbasis outcome berjalan tanpa web_search dan web_fetch, terlepas dari pengaturan ini.
• Anda dapat mengubah daftar pada sesi yang idle dengan memperbarui alatnya. Daftar baru berlaku untuk sisa sesi; dalam sesi multiagen, setiap thread menerapkannya mulai giliran berikutnya, sementara daftar milik agen roster sendiri tetap seperti yang ditetapkan definisi agennya saat sesi dibuat.



Perbedaan dari alat Messages API

Pengaturan ini menggunakan kosakata allowed_domains dan blocked_domains yang sama dengan pemfilteran domain pada alat server Messages API, dengan perbedaan berikut pada Managed Agents:

• Setiap daftar dibatasi hingga 64 domain.
• Domain yang didaftarkan untuk web_fetch tidak dapat menyertakan path.
• max_uses, citations, dan cache_control tidak tersedia pada toolset.



Alat kustom

Selain alat bawaan, Anda dapat mendefinisikan alat kustom. Alat kustom serupa dengan alat klien yang didefinisikan pengguna di Messages API.

Setiap alat kustom mendefinisikan sebuah kontrak: Anda menentukan operasi apa yang tersedia dan apa yang dikembalikannya, dan Claude menentukan kapan dan bagaimana memanggilnya. Model tidak pernah mengeksekusi apa pun sendiri. Model memancarkan permintaan terstruktur, kode Anda menjalankan operasinya, dan hasilnya mengalir kembali ke dalam percakapan. Lihat Aliran event sesi untuk cara menerima panggilan alat kustom dan mengembalikan hasil selama sesi.

Jika sesi Anda berjalan di sandbox self-hosted, worker environment dapat menyajikan alat kustom dari sandbox Anda, termasuk alat yang membungkus server MCP di dalam jaringan Anda.

ant beta:agents create < agent.yaml

name: Weather Agent
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
  - type: custom
    name: get_weather
    description: Get current weather for a location
    input_schema:
      type: object
      properties:
        location:
          type: string
          description: City name
      required:
        - location

Setelah Anda mendefinisikan alat kustom pada agen, agen memanggilnya selama sesi.



Praktik terbaik untuk definisi alat kustom

• Berikan deskripsi yang sangat detail. Ini adalah faktor terpenting dalam kinerja alat. Deskripsi Anda harus menjelaskan apa yang dilakukan alat dan kapan menggunakannya (dan kapan tidak). Jelaskan arti setiap parameter dan bagaimana parameter tersebut memengaruhi perilaku alat. Sebutkan peringatan atau keterbatasan penting apa pun. Semakin banyak konteks yang dapat Anda berikan kepada Claude tentang alat Anda, semakin baik Claude dalam menentukan kapan dan bagaimana menggunakannya. Targetkan tiga hingga empat kalimat untuk setiap deskripsi alat, lebih banyak jika alatnya kompleks.
• Konsolidasikan operasi terkait ke dalam lebih sedikit alat. Daripada membuat alat terpisah untuk setiap tindakan (create_pr, review_pr, merge_pr), kelompokkan ke dalam satu alat dengan parameter action. Alat yang lebih sedikit namun lebih mumpuni mengurangi ambiguitas pemilihan dan membuat permukaan alat Anda lebih mudah dinavigasi oleh Claude.
• Gunakan namespace yang bermakna dalam nama alat. Ketika alat Anda mencakup beberapa layanan atau sumber daya, awali nama dengan sumber dayanya (misalnya, db_query atau storage_read). Ini membuat pemilihan alat tidak ambigu seiring bertambahnya pustaka Anda.
• Rancang respons alat agar hanya mengembalikan informasi bersinyal tinggi. Kembalikan pengenal yang semantik dan stabil (misalnya, slug atau UUID) alih-alih referensi internal yang tidak jelas, dan sertakan hanya field yang dibutuhkan Claude untuk menentukan langkah berikutnya. Respons yang membengkak memboroskan konteks dan mempersulit Claude mengekstrak hal yang penting.



Langkah selanjutnya