Membatasi domain web search dan web fetch

Untuk mengontrol situs mana yang dapat dijangkau oleh alat web agen, tetapkan daftar domain pada entri web_search dan web_fetch dari toolset agen. Setiap entri configs ini menerima salah satu dari dua daftar:

• allowed_domains: Alat hanya dapat menjangkau host-host ini.
• blocked_domains: Alat tidak pernah dapat menjangkau host-host ini.

Setiap alat memiliki daftarnya sendiri, sehingga web_search dan web_fetch dapat memiliki pembatasan yang berbeda.

Menetapkan daftar domain pada agen

Contoh berikut membuat agen yang membatasi web_search ke dua situs dan memblokir satu host untuk web_fetch. Contoh ini juga menetapkan user_location dan max_content_tokens, yang dijelaskan di Pengaturan. Contoh tersebut kemudian mencetak array configs dari respons.

ant apply agent.md

---
name: Research Agent
model: claude-opus-5-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
---

Dalam environment cloud dengan jaringan limited, allowed_hosts milik environment juga berlaku untuk web_search dan web_fetch. Pembuatan sesi gagal dengan error 400 ketika allowed_domains dari alat web yang diaktifkan memiliki entri yang tidak berada dalam allowed_hosts. Begitu pula pembaruan sesi yang menambahkan entri semacam itu. Untuk memperbaikinya, tambahkan host ke allowed_hosts atau hapus entri dari allowed_domains. Saat runtime, panggilan web_fetch untuk URL pada host yang tidak cocok dengan allowed_hosts mengembalikan hasil error url_not_allowed. web_search menghilangkan hasil dari host semacam itu. Kedua daftar dicocokkan secara berbeda: entri alat mencakup subdomainnya, tetapi entri allowed_hosts hanya cocok dengan satu host yang persis sama kecuali diawali dengan *.. Misalnya, entri alat docs.example.com tidak berada dalam allowed_hosts berisi ["example.com"], tetapi berada dalam ["docs.example.com"] atau ["*.example.com"].

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.

Pengaturan

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

Untuk cara SDK mendefinisikan tipe entri-entri ini, lihat Jenis entri konfigurasi di SDK.

Ketika domain tidak diizinkan

web_search menghilangkan hasil yang tidak diizinkan oleh daftar domainnya. Panggilan web_fetch untuk URL yang tidak diizinkan oleh daftar domainnya mengembalikan hasil error kepada agen. Event agent.tool_result memiliki is_error: true, dan kontennya menyebutkan kode error url_not_allowed.

Aturan daftar domain

Aturan-aturan ini berlaku sama untuk allowed_domains dan blocked_domains. Permintaan yang melanggar salah satunya akan ditolak, seperti yang dijelaskan di Error validasi.

• Satu daftar per entri: Tetapkan allowed_domains atau blocked_domains pada sebuah entri, bukan keduanya.
• Ukuran daftar: Setiap daftar berisi 1 hingga 64 domain, masing-masing 1 hingga 255 karakter.
• Tidak boleh ada daftar kosong: Untuk tidak menerapkan pembatasan, hilangkan field tersebut atau kirim null.
• Tidak boleh ada duplikat: Sebuah domain hanya boleh muncul sekali dalam daftar. www.example.com dan example.com dihitung sebagai domain yang berbeda.

Apa yang dicocokkan oleh domain yang terdaftar

Domain yang terdaftar cocok dengan host tersebut dan semua 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.

Hostname dibandingkan tanpa memperhatikan huruf besar/kecil.

Format domain

Setiap domain adalah nama domain yang dapat didaftarkan, atau subdomainnya, yang ditulis sebagai hostname polos. Domain dapat berisi huruf ASCII, angka, tanda hubung, garis bawah, dan titik. Satu / di akhir akan diabaikan.

Domain juga ditolak jika berisi kredensial atau spasi, atau jika salah satu labelnya diawali atau diakhiri dengan tanda hubung. localhost dan host yang berakhiran .localhost, .local, .internal, .localdomain, atau .invalid juga ditolak.

Sufiks path pada domain web search

Domain web_search dapat membawa sufiks path, seperti example.com/blog. Path tidak boleh berisi spasi, ?, #, atau karakter apa pun dari $ , | ^ !.

Utamakan hostname polos untuk web_search juga. Penyedia pencarian mencocokkan sufiks path sebagai pola URL, bukan sebagai aturan host yang ketat.

Error validasi

API memvalidasi pengaturan ini saat Anda membuat agen atau memperbarui agen. API juga memvalidasinya saat Anda membuat atau memperbarui sesi yang menyertakan tools.

Pelanggaran format dan batas ditolak dengan 400 invalid_request_error:

Pada permintaan yang sama, API 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 oleh penyedia pencarian. Pesannya diakhiri dengan user_location.country: not a country the search provider supports.
• user_location.timezone yang bukan nama IANA yang valid.

Dalam environment cloud dengan jaringan limited, pembuatan dan pembaruan sesi juga memeriksa allowed_domains terhadap allowed_hosts milik environment. Lihat aturannya di Menetapkan daftar domain pada agen.

Ketika pengaturan yang diterima tidak lagi 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. Sesi kemudian kembali ke idle tanpa mencoba ulang.

Untuk melanjutkan sesi:

1. Perbaiki pengaturan dengan memperbarui alat sesi.
2. Perbarui juga agennya, sehingga sesi baru dimulai dengan konfigurasi yang sudah diperbaiki.
3. Kirim user.message baru.

Sesi multiagen dan berbasis outcome

Dalam sesi multiagen, setiap daftar domain yang berlaku untuk sebuah thread diberlakukan secara bersamaan. Agen dalam roster koordinator terikat oleh tiga set daftar:

• allowed_domains dan blocked_domains miliknya sendiri
• Milik agen mana pun yang memanggilnya
• Daftar koordinator saat ini

Pengaturan digabungkan sebagai berikut:

Dengan demikian, agen roster dapat mempersempit apa yang dijangkau alat tetapi tidak pernah memperluasnya:

• Agen roster yang menetapkan blocked_domains mempertahankan allowed_domains milik koordinator dan memblokir host-host tersebut di dalamnya.
• Agen roster yang menetapkan allowed_domains miliknya sendiri hanya dapat menjangkau host yang dicakup oleh daftarnya dan daftar koordinator.

Entri roster {"type": "self"} tidak memiliki pengaturan web sendiri dan mengikuti pengaturan koordinator saat ini.

Jika daftar allowed_domains yang digabungkan tidak memiliki domain yang sama, alat tetap tersedia bagi agen tersebut tetapi setiap panggilan gagal. Setiap panggilan mengembalikan error url_not_allowed yang menyatakan bahwa tidak ada domain yang diizinkan. Deskripsi alat juga memberi tahu model hal yang sama. Untuk menghindari hal ini, pastikan allowed_domains setiap agen roster berada di dalam daftar milik koordinator.

Grader dalam sesi berbasis outcome berjalan tanpa web_search dan web_fetch, terlepas dari pengaturan ini.

Mengubah daftar di tengah sesi

Anda dapat mengubah daftar pada sesi yang sedang idle dengan memperbarui alatnya. Daftar baru berlaku untuk sisa sesi.

Dalam sesi multiagen, setiap thread menerapkan daftar baru mulai dari giliran berikutnya. Pembaruan tidak mengubah daftar milik agen roster itu sendiri. Daftar tersebut tetap seperti yang ditetapkan oleh definisi agen saat sesi dibuat.

Perbedaan dari alat Messages API

Pengaturan ini menggunakan field allowed_domains dan blocked_domains yang sama seperti pemfilteran domain pada alat server Messages API. Managed Agents berbeda dalam empat hal:

• Setiap daftar dibatasi hingga 64 domain.
• Domain yang didaftarkan untuk web_fetch tidak boleh menyertakan path.
• Domain harus berupa ASCII. Messages API menerima entri Unicode, meskipun tidak merekomendasikannya.
• max_uses, citations, dan cache_control tidak tersedia pada toolset.

Langkah selanjutnya