도구

에이전트에서 사용할 수 있는 도구를 구성합니다.

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

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

사용 가능한 도구

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

도구	이름	설명
Bash	`bash`	셸 세션에서 bash 명령 실행
Read	`read`	샌드박스 파일 시스템에서 파일 읽기
Write	`write`	샌드박스 파일 시스템에 파일 쓰기
Edit	`edit`	파일에서 문자열 교체 수행
Glob	`glob`	glob 패턴을 사용한 빠른 파일 패턴 매칭
Grep	`grep`	정규식 패턴을 사용한 텍스트 검색
Web fetch	`web_fetch`	URL에서 콘텐츠 가져오기
Web search	`web_search`	웹에서 정보 검색

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

도구 세트 구성

에이전트를 생성할 때 agent_toolset_20260401로 전체 도구 세트를 활성화하세요. configs 배열을 사용하여 특정 도구를 비활성화하거나 설정을 재정의할 수 있습니다. 각 config 항목은 도구 호출이 자동 승인되는지 또는 확인이 필요한지를 제어하는 permission_policy도 설정할 수 있습니다. 사용 가능한 정책 유형은 권한 정책을 참조하세요.

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

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

특정 도구 비활성화

도구를 비활성화하려면 에이전트의 tools 배열에 있는 도구 세트 객체의 config 항목에서 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 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

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

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

설정	적용 대상	설명
`allowed_domains`	`web_search`, `web_fetch`	도구가 접근할 수 있는 유일한 호스트입니다. 동일한 항목에서 `blocked_domains`와 함께 사용할 수 없습니다.
`blocked_domains`	`web_search`, `web_fetch`	도구가 접근할 수 없는 호스트입니다.
`max_content_tokens`	`web_fetch`	컨텍스트에 포함되는 가져온 페이지 콘텐츠의 양을 제한합니다. 양의 정수여야 합니다. 콘텐츠 제한을 참조하세요.
`user_location`	`web_search`	검색 결과를 현지화합니다. Messages API `user_location` 매개변수와 동일한 필드를 가진 객체입니다.

도메인 목록 규칙

항목에 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에 나열된 도메인은 경로를 포함할 수 없습니다.
max_uses, citations, cache_control은 도구 세트에서 사용할 수 없습니다.

커스텀 도구

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

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

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

ant beta:agents create < agent.yaml

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

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

커스텀 도구 정의 모범 사례

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

다음 단계

MCP 커넥터

외부 도구 및 데이터 소스에 접근할 수 있도록 MCP 서버를 에이전트에 연결하세요.

권한 정책

에이전트 및 MCP 도구가 실행되는 시점을 제어하세요.

세션 이벤트 스트림

이벤트를 보내고, 응답을 스트리밍하고, 실행 중에 세션을 중단하거나 리디렉션하세요.

Was this page helpful?

Managed Agents에이전트 정의

도구

에이전트에서 사용할 수 있는 도구를 구성합니다.

사용 가능한 도구

도구	이름	설명
Bash	`bash`	셸 세션에서 bash 명령 실행
Read	`read`	샌드박스 파일 시스템에서 파일 읽기
Write	`write`	샌드박스 파일 시스템에 파일 쓰기
Edit	`edit`	파일에서 문자열 교체 수행
Glob	`glob`	glob 패턴을 사용한 빠른 파일 패턴 매칭
Grep	`grep`	정규식 패턴을 사용한 텍스트 검색
Web fetch	`web_fetch`	URL에서 콘텐츠 가져오기
Web search	`web_search`	웹에서 정보 검색

도구 세트 구성

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

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

특정 도구 비활성화

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

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

특정 도구만 활성화

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

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

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

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

설정	적용 대상	설명
`allowed_domains`	`web_search`, `web_fetch`	도구가 접근할 수 있는 유일한 호스트입니다. 동일한 항목에서 `blocked_domains`와 함께 사용할 수 없습니다.
`blocked_domains`	`web_search`, `web_fetch`	도구가 접근할 수 없는 호스트입니다.
`max_content_tokens`	`web_fetch`	컨텍스트에 포함되는 가져온 페이지 콘텐츠의 양을 제한합니다. 양의 정수여야 합니다. 콘텐츠 제한을 참조하세요.
`user_location`	`web_search`	검색 결과를 현지화합니다. Messages API `user_location` 매개변수와 동일한 필드를 가진 객체입니다.

도메인 목록 규칙

항목에 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은 서로 다른 도메인으로 간주됩니다. 각각이 포함하는 범위는 앞서 설명한 매칭 규칙을 참조하세요.

설정이 검증되는 시점

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

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

Messages API 도구와의 차이점

각 목록은 최대 64개의 도메인으로 제한됩니다.
web_fetch에 나열된 도메인은 경로를 포함할 수 없습니다.
max_uses, citations, cache_control은 도구 세트에서 사용할 수 없습니다.

커스텀 도구

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

ant beta:agents create < agent.yaml

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

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

커스텀 도구 정의 모범 사례

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

다음 단계

MCP 커넥터

외부 도구 및 데이터 소스에 접근할 수 있도록 MCP 서버를 에이전트에 연결하세요.

권한 정책

에이전트 및 MCP 도구가 실행되는 시점을 제어하세요.

세션 이벤트 스트림

이벤트를 보내고, 응답을 스트리밍하고, 실행 중에 세션을 중단하거나 리디렉션하세요.

Was this page helpful?

사용 가능한 도구

도구 세트 구성

특정 도구 비활성화

특정 도구만 활성화

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

도메인 목록 규칙

설정이 검증되는 시점

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

Messages API 도구와의 차이점

커스텀 도구

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

다음 단계

사용 가능한 도구

도구 세트 구성

특정 도구 비활성화

특정 도구만 활성화

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

도메인 목록 규칙

설정이 검증되는 시점

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

Messages API 도구와의 차이점

커스텀 도구

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

다음 단계

사용 가능한 도구

도구 세트 구성

특정 도구 비활성화

특정 도구만 활성화

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

도메인 목록 규칙

설정이 검증되는 시점

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

Messages API 도구와의 차이점

커스텀 도구

커스텀 도구 정의 모범 사례

다음 단계

사용 가능한 도구

도구 세트 구성

특정 도구 비활성화

특정 도구만 활성화

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

도메인 목록 규칙

설정이 검증되는 시점

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

Messages API 도구와의 차이점

커스텀 도구

커스텀 도구 정의 모범 사례

다음 단계