웹 검색 및 웹 가져오기 도메인 제한

에이전트의 웹 도구가 접근할 수 있는 사이트를 제어하려면 에이전트 도구 세트의 web_search 및 web_fetch 항목에 도메인 목록을 설정하세요. 이러한 configs 항목은 각각 다음 두 가지 목록 중 하나를 받습니다.

• allowed_domains: 도구가 이 호스트에만 접근할 수 있습니다.
• blocked_domains: 도구가 이 호스트에 절대 접근할 수 없습니다.

각 도구는 자체 목록을 가지므로 web_search와 web_fetch에 서로 다른 제한을 적용할 수 있습니다.

에이전트에 도메인 목록 설정

다음 예제는 web_search를 두 개의 사이트로 제한하고 web_fetch에 대해 하나의 호스트를 차단하는 에이전트를 생성합니다. 또한 설정에서 설명하는 user_location과 max_content_tokens도 설정합니다. 그런 다음 예제는 응답에서 configs 배열을 출력합니다.

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
---

limited 네트워킹을 사용하는 클라우드 환경에서는 환경의 allowed_hosts도 web_search와 web_fetch에 적용됩니다. 활성화된 웹 도구의 allowed_domains에 allowed_hosts 범위에 속하지 않는 항목이 있으면 세션 생성이 400 오류로 실패합니다. 그러한 항목을 추가하는 세션 업데이트도 마찬가지입니다. 이를 해결하려면 해당 호스트를 allowed_hosts에 추가하거나 allowed_domains에서 해당 항목을 제거하세요. 런타임에 allowed_hosts와 일치하지 않는 호스트의 URL에 대한 web_fetch 호출은 url_not_allowed 오류 결과를 반환합니다. web_search는 해당 호스트의 결과를 제외합니다. 두 목록은 일치 방식이 다릅니다. 도구의 항목은 하위 도메인까지 포함하지만, allowed_hosts 항목은 *.로 시작하지 않는 한 정확히 하나의 호스트와만 일치합니다. 예를 들어 도구 항목 docs.example.com은 ["example.com"]이라는 allowed_hosts의 범위에 속하지 않지만, ["docs.example.com"] 또는 ["*.example.com"]의 범위에는 속합니다.

Claude Console에서는 에이전트 양식의 Built-in tools 카드에 있는 web_search 및 web_fetch 행에서 허용 또는 차단할 도메인을 설정하세요. max_content_tokens와 user_location은 에이전트 구성의 Raw 보기에서 설정하세요.

설정

enabled 및 permission_policy 외에도 웹 도구 항목은 다음 설정을 받습니다.

SDK에서 이러한 항목의 타입이 지정되는 방식은 SDK의 구성 항목 타입을 참조하세요.

도메인이 허용되지 않는 경우

web_search는 도메인 목록이 허용하지 않는 결과를 제외합니다. 도메인 목록이 허용하지 않는 URL에 대한 web_fetch 호출은 에이전트에 오류 결과를 반환합니다. agent.tool_result 이벤트에는 is_error: true가 있으며, 그 콘텐츠에 오류 코드 url_not_allowed가 명시됩니다.

도메인 목록 규칙

이 규칙은 allowed_domains와 blocked_domains에 똑같이 적용됩니다. 규칙을 위반한 요청은 검증 오류에서 설명하는 대로 거부됩니다.

• 항목당 하나의 목록: 한 항목에 allowed_domains 또는 blocked_domains 중 하나만 설정하세요. 둘 다 설정할 수 없습니다.
• 목록 크기: 각 목록은 1개에서 64개의 도메인을 포함하며, 각 도메인은 1자에서 255자입니다.
• 빈 목록 불가: 제한을 적용하지 않으려면 필드를 생략하거나 null을 보내세요.
• 중복 불가: 도메인은 목록에 한 번만 나타날 수 있습니다. www.example.com과 example.com은 서로 다른 도메인으로 간주됩니다.

나열된 도메인이 일치하는 대상

나열된 도메인은 해당 호스트와 그 모든 하위 도메인에 일치합니다. example.com은 docs.example.com을 포함하지만, docs.example.com은 example.com이나 api.example.com을 포함하지 않습니다.

앞에 붙는 www.는 다른 하위 도메인과 마찬가지로 하위 도메인이므로 www.example.com은 example.com을 포함하지 않습니다. 둘 다 포함하려면 www.가 없는 도메인을 나열하세요.

호스트 이름은 대소문자를 구분하지 않고 비교됩니다.

도메인 형식

각 도메인은 등록 가능한 도메인 이름 또는 그 하위 도메인이며, 일반 호스트 이름으로 작성합니다. ASCII 문자, 숫자, 하이픈, 밑줄, 점을 포함할 수 있습니다. 끝에 붙는 / 하나는 무시됩니다.

자격 증명이나 공백이 포함된 도메인, 또는 레이블이 하이픈으로 시작하거나 끝나는 도메인도 거부됩니다. localhost와 .localhost, .local, .internal, .localdomain, .invalid로 끝나는 호스트도 거부됩니다.

웹 검색 도메인의 경로 접미사

web_search 도메인에는 example.com/blog와 같은 경로 접미사를 붙일 수 있습니다. 경로에는 공백, ?, #, 또는 $ , | ^ ! 문자를 포함할 수 없습니다.

web_search에서도 일반 호스트 이름을 사용하는 것이 좋습니다. 검색 제공자는 경로 접미사를 엄격한 호스트 규칙이 아닌 URL 패턴으로 일치시킵니다.

검증 오류

API는 에이전트를 생성하거나 에이전트를 업데이트할 때 이러한 설정을 검증합니다. tools를 제공하는 세션을 생성하거나 업데이트할 때도 검증합니다.

형식 및 제한 위반은 400 invalid_request_error로 거부됩니다.

같은 요청에서 API는 검색 및 가져오기 제공자에 의존하는 세 가지 설정도 거부합니다.

• Anthropic의 크롤러가 접근할 수 없는 allowed_domains의 도메인.
• 검색 제공자가 지원하지 않는 user_location.country. 메시지는 user_location.country: not a country the search provider supports로 끝납니다.
• 유효한 IANA 이름이 아닌 user_location.timezone.

limited 네트워킹을 사용하는 클라우드 환경에서는 세션 생성 및 업데이트 시 allowed_domains를 환경의 allowed_hosts와도 대조하여 확인합니다. 에이전트에 도메인 목록 설정의 규칙을 참조하세요.

허용되었던 설정이 더 이상 유효하지 않은 경우

세션은 도구를 처음 초기화할 때 구성을 다시 확인합니다. 이전에 허용되었던 설정이 그 시점에 더 이상 유효하지 않으면 세션은 session.error 이벤트를 발생시킵니다. 그런 다음 재시도 없이 idle 상태로 돌아갑니다.

세션을 계속하려면 다음을 수행하세요.

1. 세션의 도구를 업데이트하여 설정을 수정합니다.
2. 새 세션이 수정된 구성으로 시작되도록 에이전트도 업데이트합니다.
3. 새 user.message를 보냅니다.

멀티에이전트 및 결과 기반 세션

멀티에이전트 세션에서는 스레드에 적용되는 모든 도메인 목록이 동시에 적용됩니다. 코디네이터의 명단에 있는 에이전트는 세 가지 목록 집합의 제약을 받습니다.

• 자신의 allowed_domains 및 blocked_domains
• 자신을 호출한 모든 에이전트의 목록
• 코디네이터의 현재 목록

설정은 다음과 같이 결합됩니다.

따라서 명단 에이전트는 도구가 접근하는 범위를 좁힐 수는 있지만 넓힐 수는 없습니다.

• blocked_domains를 설정한 명단 에이전트는 코디네이터의 allowed_domains를 유지하면서 그 범위 내에서 해당 호스트를 차단합니다.
• 자체 allowed_domains를 설정한 명단 에이전트는 자신의 목록과 코디네이터의 목록이 모두 포함하는 호스트에만 접근할 수 있습니다.

{"type": "self"} 명단 항목에는 자체 웹 설정이 없으며 코디네이터의 현재 설정을 따릅니다.

결합된 allowed_domains 목록에 공통 도메인이 없으면 도구는 해당 에이전트에서 계속 사용할 수 있지만 모든 호출이 실패합니다. 각 호출은 허용되는 도메인이 없다는 url_not_allowed 오류를 반환합니다. 도구 설명도 모델에 같은 내용을 알려 줍니다. 이를 방지하려면 각 명단 에이전트의 allowed_domains를 코디네이터의 목록 안에 유지하세요.

결과 기반 세션의 채점기는 이러한 설정과 관계없이 web_search와 web_fetch 없이 실행됩니다.

세션 중간에 목록 변경

도구를 업데이트하여 유휴 세션의 목록을 변경할 수 있습니다. 새 목록은 세션의 나머지 부분에 적용됩니다.

멀티에이전트 세션에서는 모든 스레드가 다음 턴부터 새 목록을 적용합니다. 이 업데이트는 명단 에이전트 자체의 목록을 변경하지 않습니다. 해당 목록은 세션이 생성될 때 에이전트 정의가 설정한 그대로 유지됩니다.

Messages API 도구와의 차이점

이러한 설정은 Messages API 서버 도구의 도메인 필터링과 동일한 allowed_domains 및 blocked_domains 필드를 사용합니다. Managed Agents는 네 가지 점에서 다릅니다.

• 각 목록은 64개 도메인으로 제한됩니다.
• web_fetch에 나열된 도메인에는 경로를 포함할 수 없습니다.
• 도메인은 ASCII여야 합니다. Messages API는 유니코드 항목을 허용하지만 사용하지 않을 것을 권장합니다.
• max_uses, citations, cache_control은 도구 세트에서 사용할 수 없습니다.

다음 단계