도구

Claude Managed Agents는 Claude가 세션 내에서 자율적으로 사용할 수 있는 내장 도구 세트를 제공합니다. 에이전트 구성에서 도구를 지정하여 사용 가능한 도구를 제어할 수 있습니다.

Claude Managed Agents는 사용자 정의 커스텀 도구도 지원합니다. 애플리케이션이 이러한 도구를 별도로 실행하고 결과를 Claude에 반환하면, Claude는 그 결과를 사용하여 작업을 계속합니다. MCP 서버의 도구를 에이전트에 제공하려면 대신 MCP 커넥터를 사용하세요.

사용 가능한 도구

에이전트 "toolset"(도구 세트)에는 다음 도구가 포함됩니다. 에이전트 구성에 도구 세트를 포함하면 모든 도구가 기본적으로 활성화됩니다. configs 배열의 각 항목은 이름 열의 값을 사용하는 name으로 식별되며, 동일한 값을 갖는 선택적 type 필드를 허용합니다. web_search 및 web_fetch 항목은 추가 설정을 허용합니다. 웹 검색 및 웹 가져오기 도메인 제한을 참조하세요.

도구 출력이 100,000자(약 25,000 토큰)를 초과하면 샌드박스의 파일에 자동으로 기록됩니다. 모델은 파일 경로가 포함된 잘린 미리보기를 받으며, 해당 위치에서 전체 콘텐츠를 읽을 수 있습니다.

도구 세트 구성

에이전트를 생성할 때 agent_toolset_20260401로 전체 도구 세트를 활성화하세요. configs 배열을 사용하여 특정 도구를 비활성화하거나 설정을 재정의할 수 있습니다. 각 구성 항목은 도구 호출을 확인 없이 실행할지, 확인을 요구할지, 또는 서버가 개별적으로 평가할지를 제어하는 permission_policy도 설정할 수 있습니다. 사용 가능한 정책 유형은 권한 정책을 참조하세요.

web_search 및 web_fetch의 구성 항목은 도메인 필터 및 기타 웹 설정도 허용합니다. 웹 검색 및 웹 가져오기 도메인 제한을 참조하세요.

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
---

특정 도구 비활성화

도구를 비활성화하려면 에이전트의 tools 배열에 있는 도구 세트 객체에서 해당 도구의 구성 항목에 enabled: false를 설정하세요:

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

특정 도구만 활성화

default_config 객체는 세트의 모든 도구에 대한 기준을 설정하며, 도구별 configs 항목이 이를 재정의합니다. 모든 도구를 끈 상태에서 시작하여 필요한 도구만 활성화하려면 default_config.enabled를 false로 설정하세요:

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

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

에이전트의 웹 도구가 접근할 수 있는 사이트를 제어하려면 도구 세트의 configs 배열에 있는 web_search 및 web_fetch 항목에 allowed_domains(도구가 이 호스트에만 접근할 수 있음) 또는 blocked_domains(도구가 이 호스트에 절대 접근할 수 없음)를 설정하세요. 각 도구는 자체 목록을 가지므로 web_search와 web_fetch에 서로 다른 제한을 둘 수 있습니다. 목록에 있는 도메인은 해당 호스트와 모든 하위 도메인을 포함합니다. 런타임에 목록에서 허용하지 않는 URL에 대한 web_fetch 호출은 에이전트에 오류 결과를 반환하며(agent.tool_result 이벤트에 is_error: true가 설정되고, 콘텐츠에 오류 코드 url_not_allowed가 명시됨), web_search는 목록에서 허용하지 않는 결과를 생략합니다.

다음 도구 세트는 web_search를 두 사이트로 제한하고 결과를 현지화하며, web_fetch에 대해 하나의 호스트를 차단하는 동시에 컨텍스트에 들어가는 가져온 콘텐츠의 양을 제한합니다:

{
  "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
    }
  ]
}

다음 요청은 이 도구 세트로 에이전트를 생성하고 응답에서 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
---

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

enabled 및 permission_policy 외에도 웹 도구 항목은 다음 설정을 허용합니다:

도메인 목록 규칙

• 항목에는 allowed_domains 또는 blocked_domains 중 하나만 설정하고, 둘 다 설정하지 마세요. 둘 다 설정한 항목은 거부됩니다.
• 각 목록에는 1~64개의 도메인이 포함되며, 각 도메인은 1~255자입니다. 빈 목록은 거부됩니다. 제한을 적용하지 않으려면 필드를 생략하거나 null을 보내세요.
• 각 도메인은 등록 가능한 도메인 이름 또는 그 하위 도메인이며, 일반 호스트 이름으로 작성합니다. ASCII 문자, 숫자, 하이픈, 밑줄, 점만 사용할 수 있으며, 스킴, 포트, 자격 증명, 와일드카드, 공백을 포함할 수 없고, 하이픈으로 시작하거나 끝나는 레이블을 포함할 수 없으며, 이 목록의 뒷부분에서 설명하는 선택적 web_search 경로 접미사 외의 경로를 포함할 수 없습니다. https://example.com, example.com:443, *.example.com이 아닌 example.com을 사용하세요. 호스트 이름은 대소문자를 구분하지 않고 비교되며, 끝에 있는 단일 /는 무시됩니다.
• 목록에 있는 도메인은 해당 호스트와 그 하위 도메인에 일치합니다. example.com은 docs.example.com을 포함하지만, docs.example.com은 example.com이나 api.example.com을 포함하지 않습니다. 앞에 붙은 www.도 다른 하위 도메인과 마찬가지이므로 www.example.com은 example.com을 포함하지 않습니다. 둘 다 포함하려면 기본 도메인을 목록에 추가하세요.
• IP 주소는 IPv4, IPv6, 대괄호 표기, 127.1과 같은 숫자 축약형 등 어떤 형식으로도 허용되지 않습니다. 대신 사이트의 도메인 이름을 목록에 추가하세요.
• com, co.uk, gov.uk와 같은 최상위 도메인 또는 레지스트리 접미사만 단독으로 사용하면 거부되며, intranet과 같은 단일 레이블 이름도 거부됩니다. example.co.uk와 같은 전체 도메인을 목록에 추가하세요.
• localhost 및 .localhost, .local, .internal, .localdomain, .invalid로 끝나는 호스트는 거부됩니다.
• 국제화 도메인 이름에는 xn--(Punycode) 형식을 사용하세요. 비ASCII 문자가 포함된 도메인은 거부됩니다.
• web_fetch 도메인에는 경로를 포함할 수 없습니다. example.com/*이 아닌 example.com을 사용하세요. web_search 도메인에는 example.com/blog와 같은 경로 접미사를 포함할 수 있으며, 이 경로에는 공백, ?, # 또는 $ , | ^ ! 문자를 포함할 수 없습니다. 검색 제공자는 경로 접미사를 엄격한 호스트 규칙이 아닌 URL 패턴으로 매칭하므로 web_search에도 일반 호스트 이름을 사용하는 것이 좋습니다.
• 목록 내 중복 도메인은 거부됩니다. www.example.com과 example.com은 서로 다른 도메인으로 간주됩니다. 각각이 포함하는 범위는 앞의 매칭 규칙을 참조하세요.

설정 검증 시점

형식 및 제한 위반은 에이전트를 생성하거나 에이전트를 업데이트할 때, 그리고 tools를 제공하는 세션을 생성하거나 업데이트할 때 400 invalid_request_error로 거부됩니다. 예를 들어, 두 목록을 모두 설정한 항목에 대한 메시지에는 Only one of allowed_domains or blocked_domains may be set.이 포함되고, 빈 목록에 대한 메시지에는 allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null.이 포함됩니다. 형식 규칙을 위반한 도메인에 대한 메시지에는 해당 목록과 0부터 시작하는 위치가 명시됩니다. 예: allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com".

동일한 요청은 검색 및 가져오기 제공자에 따라 달라지는 세 가지 설정도 거부합니다. Anthropic의 크롤러가 접근할 수 없는 allowed_domains의 도메인, 검색 제공자가 지원하지 않는 user_location.country(메시지가 user_location.country: not a country the search provider supports로 끝남), 유효한 IANA 이름이 아닌 user_location.timezone입니다. 세션은 도구를 처음 초기화할 때 구성을 다시 확인합니다. 이전에 허용된 설정이 그 시점에 더 이상 유효하지 않으면, 세션은 session.error 이벤트를 발생시키고 재시도 없이 idle 상태로 돌아갑니다. 세션의 도구를 업데이트하여 설정을 수정하고, 새 세션이 수정된 구성으로 시작되도록 에이전트도 업데이트한 다음, 새 user.message를 보내 계속 진행하세요.

멀티에이전트 세션, 결과 및 세션 중 업데이트

멀티에이전트 세션에서는 스레드에 적용되는 모든 도메인 목록이 동시에 적용됩니다. 코디네이터의 로스터에 있는 에이전트는 자체 allowed_domains 및 blocked_domains, 자신을 호출한 모든 에이전트의 목록, 그리고 코디네이터의 현재 목록의 제약을 받습니다.

• 허용 목록은 모든 목록이 공통으로 포함하는 도메인으로 결합되고, 차단 목록은 합산되므로, 로스터 에이전트는 도구가 접근하는 범위를 좁힐 수는 있지만 넓힐 수는 없습니다. 예를 들어, blocked_domains를 설정한 로스터 에이전트는 코디네이터의 allowed_domains를 유지하면서 그 안에서 해당 호스트를 차단하며, 자체 allowed_domains를 설정한 로스터 에이전트는 자신의 목록과 코디네이터의 목록이 모두 포함하는 호스트에만 접근할 수 있습니다.
• 결합된 허용 목록에 공통 도메인이 없으면, 해당 에이전트에서 도구는 계속 사용 가능하지만 모든 호출이 허용된 도메인이 없다는 url_not_allowed 오류로 실패하며, 도구 설명이 모델에 이를 알립니다. 이를 방지하려면 각 로스터 에이전트의 허용 목록을 코디네이터의 허용 목록 범위 내로 유지하세요.
• max_content_tokens 및 user_location은 결합되지 않습니다. 스레드는 자체 도구 구성에 값이 설정되어 있으면 그 값을 사용하고, 그렇지 않으면 자신을 호출한 에이전트의 값을, 그것도 없으면 코디네이터의 현재 구성 값을 사용합니다.
• {"type": "self"} 로스터 항목은 자체 웹 설정이 없으며 코디네이터의 현재 설정을 따릅니다.
• 결과 기반 세션의 채점기는 이러한 설정과 관계없이 web_search 및 web_fetch 없이 실행됩니다.
• 유휴 세션의 목록은 도구를 업데이트하여 변경할 수 있습니다. 새 목록은 세션의 나머지 기간에 적용됩니다. 멀티에이전트 세션에서는 모든 스레드가 다음 턴부터 새 목록을 적용하지만, 로스터 에이전트의 자체 목록은 세션 생성 시 에이전트 정의에서 설정된 대로 유지됩니다.

Messages API 도구와의 차이점

이러한 설정은 Messages API 서버 도구의 도메인 필터링과 동일한 allowed_domains 및 blocked_domains 용어를 사용하지만, Managed Agents에서는 다음과 같은 차이점이 있습니다:

• 각 목록은 최대 64개의 도메인으로 제한됩니다.
• web_fetch에 나열된 도메인에는 경로를 포함할 수 없습니다.
• 도메인은 ASCII여야 합니다. 국제화 도메인 이름에는 xn--(Punycode) 형식을 사용하세요. Messages API는 유니코드 항목을 허용하지만 사용을 권장하지 않습니다.
• max_uses, citations, cache_control은 도구 세트에서 사용할 수 없습니다.

커스텀 도구

내장 도구 외에도 커스텀 도구를 정의할 수 있습니다. 커스텀 도구는 Messages API의 사용자 정의 클라이언트 도구와 유사합니다.

각 커스텀 도구는 계약을 정의합니다. 사용 가능한 작업과 그 반환 값을 지정하면, Claude가 언제 어떻게 호출할지 결정합니다. 모델은 스스로 아무것도 실행하지 않습니다. 모델이 구조화된 요청을 생성하면 코드가 작업을 실행하고, 그 결과가 대화로 다시 전달됩니다. 세션 중에 커스텀 도구 호출을 수신하고 결과를 반환하는 방법은 세션 이벤트 스트림을 참조하세요.

세션이 자체 호스팅 샌드박스에서 실행되는 경우, 환경 워커는 네트워크 내부의 MCP 서버를 래핑하는 도구를 포함하여 샌드박스에서 커스텀 도구를 제공할 수 있습니다.

ant apply agent.md

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

에이전트에 커스텀 도구를 정의하면, 에이전트는 세션 중에 해당 도구를 호출합니다.

커스텀 도구 정의 모범 사례

• 매우 상세한 설명을 제공하세요. 이는 도구 성능에 있어 단연 가장 중요한 요소입니다. 설명에는 도구가 무엇을 하는지, 언제 사용해야 하는지(그리고 언제 사용하지 말아야 하는지)를 설명해야 합니다. 각 매개변수의 의미와 도구 동작에 미치는 영향을 설명하세요. 중요한 주의 사항이나 제한 사항을 명시하세요. 도구에 대해 Claude에 더 많은 컨텍스트를 제공할수록 Claude가 도구를 언제 어떻게 사용할지 더 잘 판단할 수 있습니다. 각 도구 설명은 3~4문장을 목표로 하고, 도구가 복잡하다면 더 길게 작성하세요.
• 관련 작업을 더 적은 수의 도구로 통합하세요. 모든 작업마다 별도의 도구(create_pr, review_pr, merge_pr)를 만드는 대신, action 매개변수를 가진 단일 도구로 묶으세요. 더 적고 더 강력한 도구는 선택의 모호성을 줄이고 Claude가 도구 구성을 더 쉽게 탐색할 수 있게 합니다.
• 도구 이름에 의미 있는 네임스페이스를 사용하세요. 도구가 여러 서비스나 리소스에 걸쳐 있는 경우, 이름 앞에 리소스를 접두사로 붙이세요(예: db_query 또는 storage_read). 이렇게 하면 라이브러리가 커져도 도구 선택이 명확해집니다.
• 도구 응답이 신호가 높은 정보만 반환하도록 설계하세요. 불투명한 내부 참조 대신 의미 있고 안정적인 식별자(예: 슬러그 또는 UUID)를 반환하고, Claude가 다음 단계를 결정하는 데 필요한 필드만 포함하세요. 비대한 응답은 컨텍스트를 낭비하고 Claude가 중요한 정보를 추출하기 어렵게 만듭니다.

다음 단계