도구

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

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

사용 가능한 도구

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

도구 세트 구성

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

특정 도구 비활성화

도구를 비활성화하려면 해당 구성 항목에서 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가 언제 어떻게 호출할지 결정합니다. 모델은 자체적으로 아무것도 실행하지 않습니다. 구조화된 요청을 내보내고 코드가 작업을 실행한 후 결과가 대화로 다시 흘러들어옵니다.

에이전트 수준에서 도구를 정의한 후 에이전트는 세션 과정에서 도구를 호출합니다. 전체 흐름은 세션 이벤트 스트림을 참조하세요.

사용자 정의 도구 정의의 모범 사례

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