기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

도구 정의

LLM은 직접 처리할 수 없는 요청을 수신하면 사용 가능한 도구를 검토하여 요청을 완료하는 데 도움이 됩니다. LLM은 제공된 도구의 이름 및 설명과 프롬프트에 제공된 지침에 대한 의미론적 이해를 기반으로 도구를 선택합니다. 그런 다음 정의된 입력 스키마를 기반으로 입력을 생성하고 출력 스키마를 기반으로 출력을 예상합니다. 따라서 LLM이 도구를 효과적으로 선택하는 데 도움이 되려면 설명이 포함된 도구 정의와 검증된 입력 및 출력 스키마를 만드는 것이 중요합니다. 이 설명서를 생성하는 데는 일반적으로 도구 사양 접근 방식과 문서 문자열 접근 방식이라는 두 가지 접근 방식이 있습니다.

도구 사양 접근 방식

권장되는 접근 방식은 도구를 정의할 때 MCP 도구 사양을 직접 따르는 것입니다. 다음 예제는 Strands Agent 도구 데코레이터를 사용하여 표시됩니다.

@tool(
  name = "search_website",
  description = "This tool searches the provided website for semantic matches to the query provided",
  inputSchema = {
    "json": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "The url of the website to load and search."
        },
        "query": {
          "type": "string",
          "description": "The content you want to try and match in the website."
      }
    },
    "required": ["url", "query"]
  },
  outputSchema = {
    "json": {
      "type": "object",
      "properties": {
      "results": {
          "type": "array",
          "items": {
            "type": "string" 
          }
        }
      }
    }
  }
)
def search_website:
  …

, name, inputSchema, description등의 표준 필드를 사용하면 모든 도구에 LLM과 사람이 모두 이해할 수 있는 일관된 설명서가 있는지 outputSchema 확인할 수 있습니다. 모든 도구는 최소한 이러한 필드를 정의하고 선택적으로 도구 동작에 대한 선택적 힌트인 제목과 주석을 제공해야 합니다. 가능하면 파라미터 값에 열거형을 사용하여 LLM이 올바른 옵션을 쉽게 선택할 수 있도록 합니다. 열거형은 상태 또는 우선 순위 값과 같은 유한 집합에 가장 적합하지만 자유 형식 텍스트, 동적 값, 임의 숫자 또는 리소스 식별자에는 적합하지 않습니다. 이러한 경우 대신 명확한 설명과 예제를 제공합니다. LLM이 올바른 옵션이 무엇인지 추측할 필요가 없도록 가능하면 기본값도 포함합니다. 도구 정의는 각 호출의 LLM 프롬프트에 포함되어 시스템 지침 및 대화 기록과 함께 컨텍스트 창 공간을 사용한다는 점에 유의하세요.

Docstring 접근 방식

또 다른 접근 방식인 Python으로 도구를 작성하는 경우는 문서 문자열을 사용하여 도구의 설명, 사용 및 출력을 제공하는 것입니다. 다음은이 접근 방식의 예입니다.

def search_website(url: str, query: str) -> list:
    
    """
    This tool loads the specified website and then attempts to find content that matches the provided query through semantic search. It provides back a list of strings that are the sentences that match the query. 
    Args:
      url: the website url to load
      query: the content you want to semantically match in the website
    """

Docstring은 스키마 또는 표준화된 형식을 적용하지 않습니다. 이 접근 방식을 사용하면 도구 개발자가 각 도구를 문서화하도록 선택하는 방법에 따라 일관되지 않은 결과를 얻을 수 있습니다. 이 접근 방식을 따르는 경우 조직 전체의 표준을 정의하고 적용하는 것이 중요합니다.

MCP 도구 정의 모범 사례