도구 정의

모델 선택

복잡한 도구와 모호한 쿼리의 경우 최신 Claude Opus (4.7) 모델을 사용하세요. 여러 도구를 더 잘 처리하고 필요할 때 명확히 해달라고 요청합니다.

간단한 도구의 경우 Claude Haiku 모델을 사용하되, 누락된 매개변수를 추론할 수 있다는 점에 유의하세요.

클라이언트 도구 지정

클라이언트 도구(Anthropic 스키마 및 사용자 정의 모두)는 API 요청의 tools 최상위 매개변수에서 지정됩니다. 각 도구 정의에는 다음이 포함됩니다:

cache_control, strict, defer_loading, allowed_callers를 포함한 도구 정의에서 사용 가능한 모든 선택적 속성의 전체 집합은 도구 참조를 참조하세요.

도구 사용 시스템 프롬프트

tools 매개변수를 사용하여 Claude API를 호출하면, API는 도구 정의, 도구 구성 및 사용자가 지정한 시스템 프롬프트에서 특수 시스템 프롬프트를 구성합니다. 구성된 프롬프트는 모델에게 지정된 도구를 사용하도록 지시하고 도구가 제대로 작동하기 위한 필요한 컨텍스트를 제공하도록 설계되었습니다:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

도구 정의 모범 사례

Claude를 도구와 함께 사용할 때 최고의 성능을 얻으려면 다음 지침을 따르세요:

• 매우 상세한 설명을 제공하세요. 이것이 도구 성능에 가장 중요한 요소입니다. 설명에는 다음을 포함하여 도구에 대한 모든 세부 사항을 설명해야 합니다:
  • 도구가 무엇을 하는지
  • 언제 사용해야 하는지(그리고 언제 사용하면 안 되는지)
  • 각 매개변수가 무엇을 의미하는지 및 도구의 동작에 어떻게 영향을 미치는지
  • 도구 이름이 불명확한 경우 도구가 반환하지 않는 정보 등 중요한 주의사항이나 제한사항입니다. Claude에게 도구에 대해 제공할 수 있는 컨텍스트가 많을수록 도구를 언제 어떻게 사용할지 결정하는 데 더 능숙해집니다. 도구 설명당 최소 3-4문장을 목표로 하고, 도구가 복잡하면 더 많이 작성하세요.
• 설명을 우선시하되, 복잡한 도구의 경우 input_examples 사용을 고려하세요. 명확한 설명이 가장 중요하지만, 복잡한 입력, 중첩된 객체 또는 형식에 민감한 매개변수가 있는 도구의 경우 input_examples 필드를 사용하여 스키마 검증 예제를 제공할 수 있습니다. 자세한 내용은 도구 사용 예제 제공을 참조하세요.
• 관련 작업을 더 적은 수의 도구로 통합하세요. 모든 작업에 대해 별도의 도구를 만드는 대신(create_pr, review_pr, merge_pr), action 매개변수가 있는 단일 도구로 그룹화하세요. 더 적은 수의 더 강력한 도구는 선택 모호성을 줄이고 Claude가 도구 표면을 더 쉽게 탐색할 수 있게 합니다.

좋은 설명은 도구가 무엇을 하는지, 언제 사용하는지, 어떤 데이터를 반환하는지, ticker 매개변수가 무엇을 의미하는지 명확히 설명합니다. 좋지 않은 설명은 너무 간단하고 Claude에게 도구의 동작 및 사용법에 대해 많은 미해결 질문을 남깁니다.

도구 사용 예제 제공

유효한 도구 입력의 구체적인 예제를 제공하여 Claude가 도구를 더 효과적으로 사용하는 방법을 이해하도록 도울 수 있습니다. 이는 중첩된 객체, 선택적 매개변수 또는 형식에 민감한 입력이 있는 복잡한 도구에 특히 유용합니다.

기본 사용법

도구 정의에 선택적 input_examples 필드를 추가하고 예제 입력 객체의 배열을 포함하세요. 각 예제는 도구의 input_schema에 따라 유효해야 합니다:

예제는 도구 스키마와 함께 프롬프트에 포함되어 Claude에게 잘 형성된 도구 호출의 구체적인 패턴을 보여줍니다. 이는 Claude가 선택적 매개변수를 포함할 시기, 어떤 형식을 사용할지, 복잡한 입력을 어떻게 구조화할지 이해하는 데 도움이 됩니다.

요구사항 및 제한사항

• 스키마 검증 - 각 예제는 도구의 input_schema에 따라 유효해야 합니다. 유효하지 않은 예제는 400 오류를 반환합니다
• 서버 측 도구에서는 지원되지 않음 - 입력 예제는 사용자 정의 및 Anthropic 스키마 클라이언트 도구에서 작동하지만 웹 검색 또는 코드 실행과 같은 서버 도구에서는 작동하지 않습니다
• 토큰 비용 - 예제는 프롬프트 토큰에 추가됩니다: 간단한 예제의 경우 약 20-50 토큰, 복잡한 중첩 객체의 경우 약 100-200 토큰

Claude의 출력 제어

도구 사용 강제

경우에 따라 Claude가 도구를 호출하지 않고 직접 답변하더라도 특정 도구를 사용하여 사용자의 질문에 답하도록 Claude를 강제하고 싶을 수 있습니다. tool_choice 필드에서 도구를 지정하여 이를 수행할 수 있습니다:

tool_choice = {"type": "tool", "name": "get_weather"}

tool_choice 매개변수로 작업할 때 네 가지 가능한 옵션이 있습니다:

• auto는 Claude가 제공된 도구를 호출할지 여부를 결정하도록 허용합니다. 이는 tools가 제공될 때의 기본값입니다.
• any는 Claude가 제공된 도구 중 하나를 사용해야 하지만 특정 도구를 강제하지 않습니다.
• tool은 Claude가 항상 특정 도구를 사용하도록 강제합니다.
• none은 Claude가 도구를 사용하지 못하도록 방지합니다. 이는 tools가 제공되지 않을 때의 기본값입니다.

이 다이어그램은 각 옵션이 어떻게 작동하는지 보여줍니다:

tool_choice가 any 또는 tool일 때, API는 도구를 강제로 사용하도록 어시스턴트 메시지를 미리 채웁니다. 이는 명시적으로 요청받더라도 모델이 tool_use 콘텐츠 블록 전에 자연어 응답이나 설명을 내보내지 않음을 의미합니다.

테스트 결과 이것이 성능을 감소시키지 않아야 함을 보여주었습니다. 모델이 특정 도구를 사용하도록 요청하면서도 자연어 컨텍스트나 설명을 제공하기를 원한다면, tool_choice에 {"type": "auto"} (기본값)를 사용하고 user 메시지에 명시적 지침을 추가할 수 있습니다. 예를 들어: What's the weather like in London? Use the get_weather tool in your response.

도구를 사용한 모델 응답

도구를 사용할 때, Claude는 종종 자신이 하는 일에 대해 언급하거나 도구를 호출하기 전에 사용자에게 자연스럽게 응답합니다.

예를 들어, "San Francisco의 현재 날씨는 어떻고, 거기의 시간은 몇 시인가?"라는 프롬프트가 주어지면, Claude는 다음과 같이 응답할 수 있습니다:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

이 자연스러운 응답 스타일은 사용자가 Claude가 하는 일을 이해하도록 도와주고 더 대화식의 상호작용을 만듭니다. 시스템 프롬프트와 프롬프트에 <examples>를 제공하여 이러한 응답의 스타일과 내용을 안내할 수 있습니다.

Claude가 자신의 행동을 설명할 때 다양한 표현과 접근 방식을 사용할 수 있다는 점에 유의하는 것이 중요합니다. 코드는 이러한 응답을 다른 어시스턴트 생성 텍스트처럼 취급해야 하며, 특정 형식 규칙에 의존하지 않아야 합니다.

다음 단계