도구

Claude Managed Agents는 Claude가 세션 내에서 자율적으로 사용할 수 있는 일련의 기본 제공 도구를 제공합니다. 에이전트 구성에서 도구를 지정하여 어떤 도구를 사용할 수 있는지 제어합니다.

사용자 정의 도구도 지원됩니다. 애플리케이션이 이러한 도구를 별도로 실행하고 도구 결과를 Claude에게 다시 보냅니다. Claude는 결과를 사용하여 진행 중인 작업을 계속할 수 있습니다.

사용 가능한 도구

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

도구 세트 구성

에이전트를 생성할 때 agent_toolset_20260401로 전체 도구 세트를 활성화합니다. configs 배열을 사용하여 특정 도구를 비활성화하거나 설정을 재정의합니다.

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

특정 도구 비활성화

도구를 비활성화하려면 해당 구성 항목에서 enabled: false를 설정합니다:

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

특정 도구만 활성화

모든 것을 비활성화한 상태에서 시작하여 필요한 것만 활성화하려면 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의 기능을 확장하여 더 다양한 작업을 수행할 수 있습니다. 각 도구는 계약을 정의합니다. 사용 가능한 작업과 반환되는 내용을 지정하면 Claude가 언제 어떻게 호출할지 결정합니다. 모델은 자체적으로 아무것도 실행하지 않습니다. 구조화된 요청을 내보내고 코드가 작업을 실행한 후 결과가 대화로 다시 흘러들어갑니다.

ant beta:agents create <<'YAML'
name: Weather Agent
model: claude-opus-4-7
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에게 도구에 대해 제공할 수 있는 컨텍스트가 많을수록 도구를 언제 어떻게 사용할지 결정하는 데 더 잘할 것입니다. 도구 설명당 최소 3-4개 문장을 목표로 하고, 도구가 복잡하면 더 많이 작성합니다.
• 관련 작업을 더 적은 수의 도구로 통합합니다. 모든 작업에 대해 별도의 도구를 만드는 대신(create_pr, review_pr, merge_pr), action 매개변수가 있는 단일 도구로 그룹화합니다. 더 적은 수의 더 강력한 도구는 선택 모호성을 줄이고 Claude가 도구 표면을 탐색하기 쉽게 만듭니다.
• 도구 이름에 의미 있는 네임스페이싱을 사용합니다. 도구가 여러 서비스 또는 리소스에 걸쳐 있을 때 이름 앞에 리소스를 붙입니다(예: db_query, storage_read). 이렇게 하면 라이브러리가 커질수록 도구 선택이 명확해집니다.
• 도구 응답을 설계하여 높은 신호 정보만 반환합니다. 불투명한 내부 참조 대신 의미론적이고 안정적인 식별자(예: slug 또는 UUID)를 반환하고 Claude가 다음 단계를 추론하는 데 필요한 필드만 포함합니다. 부풀려진 응답은 컨텍스트를 낭비하고 Claude가 중요한 것을 추출하기 어렵게 만듭니다.