도구

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

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



사용 가능한 도구

에이전트 도구 세트에는 다음 도구가 포함되어 있습니다. 에이전트 구성에 도구 세트를 포함하면 모든 도구가 기본적으로 활성화됩니다. configs 배열에서 도구를 참조하려면 이름 열의 값을 사용하세요.

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



도구 세트 구성

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

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
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 }
  ]
}



커스텀 도구

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

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

ant beta:agents create <<'YAML'
name: Weather Agent
model: claude-opus-4-8
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
YAML

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



커스텀 도구 정의 모범 사례

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



다음 단계