도구

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

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

사용 가능한 도구

에이전트 도구 세트에는 다음 도구가 포함됩니다. 에이전트 구성에 도구 세트를 포함하면 모든 도구가 기본적으로 활성화됩니다.

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

도구 세트 구성

에이전트를 생성할 때 agent_toolset_20260401로 전체 도구 세트를 활성화하세요. 특정 도구를 비활성화하거나 설정을 재정의하려면 configs 배열을 사용하세요. 각 항목은 name으로 식별되며, 이 값은 사용 가능한 도구의 이름 열에 있는 값을 사용합니다. 항목은 동일한 값을 갖는 선택적 type 필드도 허용합니다.

각 구성 항목은 permission_policy도 설정할 수 있습니다. 이 정책은 도구 호출이 확인 없이 실행될지, 확인이 필요할지, 또는 서버에서 개별적으로 평가될지를 제어합니다. 사용 가능한 정책 유형은 권한 정책을 참조하세요.

다음 예제는 도구 세트를 활성화하고 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
---

특정 도구 비활성화

도구를 비활성화하려면 해당 configs 항목에서 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 }
  ]
}

웹 검색 및 웹 가져오기 제한

web_search 및 web_fetch 항목은 도메인 목록, 가져온 콘텐츠의 상한, 검색 위치도 허용합니다. 웹 검색 및 웹 가져오기 도메인 제한을 참조하세요.

SDK의 구성 항목 타입

Python, TypeScript, Go, Java, C#, Ruby, PHP SDK는 각 configs 항목을 도구별로 타입 지정합니다. 이 타입은 내장 도구마다 하나의 멤버를 갖는 유니온이며, type으로 구분됩니다.

Go, Java, C#, PHP에서는 일반 딕셔너리나 해시가 아닌 타입이 지정된 값으로 항목을 구성합니다. 이러한 SDK에서는 configs의 요소 타입이 유니온 자체이므로, 각 항목을 도구별 멤버 타입으로 구성하세요.

서버가 name에서 추론하므로 항목을 구성할 때 type을 생략할 수 있습니다. 응답에는 항상 포함됩니다. 이 타입 지정은 항목이 직렬화되는 JSON을 변경하지 않습니다. 항목에 name, enabled, permission_policy만 설정된 요청은 type의 유무와 관계없이 유효합니다.

커스텀 도구

커스텀 도구는 Messages API의 사용자 정의 클라이언트 도구와 유사합니다. 사용 가능한 작업과 반환 내용을 지정하면, Claude가 언제 어떻게 호출할지 결정합니다.

Claude는 커스텀 도구를 직접 실행하지 않습니다. Claude가 구조화된 요청을 내보내면, 코드가 작업을 실행하고, 결과를 세션에 반환합니다.

다음 예제는 내장 도구 세트와 하나의 커스텀 도구 get_weather를 갖는 에이전트를 생성합니다:

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

커스텀 도구의 이름은 mcp__ 또는 ant__로 시작하거나 내장 에이전트 도구의 이름과 일치할 수 없습니다. 이 규칙을 위반하는 요청은 400 오류를 반환합니다. 이름이 ant__로 시작하는 커스텀 도구를 이미 가진 에이전트는 업데이트가 해당 이름 없이 tools를 보내는 경우에만 업데이트를 허용하므로, 다음 업데이트에서 도구의 이름을 변경하거나 제거하세요. 이러한 도구가 세션의 에이전트(재정의 적용 후), subagents의 predefined_agents 목록에 있는 에이전트, 또는 workflows의 predefined_agents 목록에 있는 에이전트에 있으면 새 세션은 400 오류와 함께 거부됩니다. 이미 존재하는 세션은 영향을 받지 않습니다.

에이전트는 세션 중에 커스텀 도구를 호출합니다. 호출을 수신하고 결과를 반환하는 방법은 세션 이벤트 스트림을 참조하세요.

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

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

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

다음 단계