Alat

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

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



Alat yang tersedia

Toolset agen mencakup alat-alat berikut. Semuanya diaktifkan secara default ketika Anda menyertakan toolset dalam konfigurasi agen Anda. Setiap entri dalam array configs diidentifikasi oleh name-nya, menggunakan nilai-nilai di 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 yang dipotong 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 disetujui secara 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 alat, atur enabled: false di entri config-nya dalam objek toolset pada 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, atur 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, atur 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 membawa 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 berapa banyak konten yang diambil masuk ke 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, atur domain yang diizinkan atau diblokir dari baris web_search dan web_fetch pada kartu Built-in tools di formulir agen; atur 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

• Atur allowed_domains atau blocked_domains pada sebuah entri, bukan keduanya. Entri yang menetapkan keduanya akan ditolak.
• Setiap daftar berisi 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 dengan tanda hubung, dan tanpa path selain sufiks path web_search opsional yang dijelaskan kemudian 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 dasarnya 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 atau sufiks registri polos seperti com, co.uk, atau gov.uk ditolak, begitu pula nama label tunggal seperti intranet. Daftarkan domain lengkap seperti example.co.uk.
• localhost dan host yang diakhiri dengan .localhost, .local, .internal, .localdomain, atau .invalid ditolak.
• Gunakan bentuk xn-- (Punycode) untuk nama domain internasional; domain yang berisi 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 dapat berisi spasi, ?, #, atau karakter $ , | ^ ! mana pun. Lebih baik gunakan hostname biasa untuk web_search juga, karena penyedia pencarian mencocokkan sufiks path sebagai pola URL alih-alih 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 apa yang dicakup masing-masing.



Kapan pengaturan divalidasi

Pelanggaran format dan batas ditolak dengan 400 invalid_request_error ketika Anda membuat agen atau memperbarui agen, dan ketika Anda membuat atau memperbarui sesi yang menyediakan tools. Misalnya, pesan untuk entri yang menetapkan kedua daftar menyertakan Only one of allowed_domains or blocked_domains may be set., dan pesan untuk daftar kosong menyertakan 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 search dan fetch: domain dalam allowed_domains yang tidak diizinkan diakses oleh crawler Anthropic, user_location.country yang tidak didukung oleh penyedia pencarian (pesan diakhiri 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 ketika pertama kali menginisialisasi alat; jika pengaturan yang diterima sebelumnya 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 agen juga agar sesi baru dimulai dengan konfigurasi yang telah diperbaiki, lalu kirim user.message baru untuk melanjutkan.



Sesi multiagent, outcome, dan pembaruan di tengah sesi

Dalam sesi multiagent, setiap daftar domain yang berlaku untuk sebuah thread diterapkan pada saat yang sama: agen dalam roster koordinator terikat oleh allowed_domains dan blocked_domains miliknya sendiri, oleh daftar 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 miliknya sendiri hanya dapat menjangkau host yang dicakup oleh daftarnya dan daftar koordinator.
• Jika allowlist gabungan tidak memiliki domain yang sama, alat tetap tersedia untuk 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 diatur, 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 idle dengan memperbarui alatnya. Daftar baru berlaku untuk sisa sesi; dalam sesi multiagent, setiap thread menerapkannya dari giliran berikutnya, sementara daftar milik agen roster sendiri tetap seperti yang ditetapkan oleh definisi agennya saat sesi dibuat.



Perbedaan dari alat Messages API

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

• Setiap daftar dibatasi hingga 64 domain.
• Domain yang terdaftar 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 analog dengan alat klien yang ditentukan 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 operasi, 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, environment worker 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 akan memanggilnya selama sesi.



Praktik terbaik untuk definisi alat kustom

• Berikan deskripsi yang sangat detail. Ini adalah faktor terpenting dalam performa alat. Deskripsi Anda harus menjelaskan apa yang dilakukan alat dan kapan menggunakannya (dan kapan tidak). Jelaskan apa arti setiap parameter dan bagaimana pengaruhnya terhadap perilaku alat. Sebutkan peringatan atau batasan 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 namespacing yang bermakna dalam nama alat. Ketika alat Anda mencakup beberapa layanan atau sumber daya, beri prefiks nama dengan sumber dayanya (misalnya, db_query atau storage_read). Ini membuat pemilihan alat tidak ambigu seiring bertambahnya pustaka Anda.
• Rancang respons alat untuk hanya mengembalikan informasi bernilai tinggi. Kembalikan pengidentifikasi 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 membuang konteks dan mempersulit Claude untuk mengekstrak apa yang penting.



Langkah selanjutnya