언어 모델 도구 API
언어 모델 도구를 사용하면 특정 도메인에 특화된 기능으로 대화에서 대규모 언어 모델(LLM)의 기능을 확장할 수 있습니다. 사용자의 채팅 프롬프트를 처리하기 위해 VS Code의 에이전트는 이러한 도구를 자동으로 호출하여 대화의 일부로 전문적인 작업을 수행할 수 있습니다.
VS Code 확장 프로그램에서 언어 모델 도구를 기여함으로써 에이전트 코드 워크플로를 확장하고 편집기와 깊이 통합할 수 있습니다. 확장 프로그램 도구는 VS Code에서 사용할 수 있는 세 가지 유형의 도구 중 하나이며, 기본 제공 도구 및 MCP 도구와 함께 제공됩니다.
이 확장 프로그램 가이드에서는 언어 모델 도구 API를 사용하여 언어 모델 도구를 만드는 방법과 채팅 확장 프로그램에서 도구 호출을 구현하는 방법을 배웁니다.
또한 MCP 서버를 기여하여 전문화된 도구로 채팅 환경을 확장할 수도 있습니다. 다양한 옵션과 어떤 접근 방식을 사용할지 결정하는 방법에 대한 자세한 내용은 AI 확장성 개요를 참조하세요.
최종 사용자로서 도구를 사용하는 방법에 대한 정보는 채팅에서 도구 사용을 참조하세요.
LLM에서 도구 호출이란 무엇인가요?
언어 모델 도구는 언어 모델 요청의 일부로 호출될 수 있는 함수입니다. 예를 들어, 데이터베이스에서 정보를 검색하거나, 계산을 수행하거나, 온라인 API를 호출하는 함수가 있을 수 있습니다. VS Code 확장 프로그램에서 도구를 기여하면 에이전트 모드에서 대화의 맥락에 따라 해당 도구를 호출할 수 있습니다.
LLM은 실제로 도구를 실행하지 않습니다. 대신 LLM은 도구를 호출하는 데 사용되는 매개변수를 생성합니다. 도구가 올바른 맥락에서 호출될 수 있도록 도구의 목적, 기능 및 입력 매개변수를 명확하게 설명하는 것이 중요합니다.
다음 다이어그램은 VS Code의 에이전트 모드에서 도구 호출 흐름을 보여줍니다. 관련 단계에 대한 자세한 내용은 도구 호출 흐름을 참조하세요.
OpenAI 설명서에서 함수 호출에 대해 자세히 알아보세요.
확장 프로그램에 언어 모델 도구를 구현하는 이유는 무엇인가요?
확장 프로그램에 언어 모델 도구를 구현하면 여러 가지 이점이 있습니다.
- 에이전트 모드 확장: 사용자 프롬프트에 응답하는 과정에서 자동으로 호출되는 전문적이고 특정 도메인에 특화된 도구를 제공합니다. 예를 들어, 데이터베이스 스캐폴딩 및 쿼리를 활성화하여 LLM에 관련 컨텍스트를 동적으로 제공할 수 있습니다.
- VS Code와 깊이 통합: 광범위한 확장 API 세트를 활용합니다. 예를 들어, 디버그 API를 사용하여 현재 디버깅 컨텍스트를 가져와 도구 기능의 일부로 사용할 수 있습니다.
- 배포 및 배포: Visual Studio Marketplace를 통해 도구를 배포하여 사용자에게 안정적이고 원활한 환경을 제공합니다. 사용자는 도구에 대해 별도의 설치 및 업데이트 프로세스가 필요하지 않습니다.
다음과 같은 시나리오에서는 MCP 서버와 함께 언어 모델 도구를 구현하는 것을 고려해 볼 수 있습니다.
- 이미 MCP 서버 구현이 있고 이를 VS Code에서도 사용하고 싶을 때.
- 다른 개발 환경 및 플랫폼 간에 동일한 도구를 재사용하고 싶을 때.
- 도구가 서비스로 원격 호스팅될 때.
- VS Code API에 액세스할 필요가 없을 때.
도구 유형 간의 차이점에 대해 자세히 알아보세요.
언어 모델 도구 만들기
언어 모델 도구를 구현하는 것은 두 가지 주요 부분으로 구성됩니다.
- 확장 프로그램의
package.json파일에 도구 구성을 정의합니다. - 확장 프로그램 코드에서 언어 모델 API 참조를 사용하여 도구를 구현합니다.
기본 예제 프로젝트로 시작할 수 있습니다.
1. package.json의 정적 구성
확장 프로그램에 언어 모델 도구를 정의하는 첫 번째 단계는 확장 프로그램의 package.json 파일에 정의하는 것입니다. 이 구성에는 도구 이름, 설명, 입력 스키마 및 기타 메타데이터가 포함됩니다.
-
확장 프로그램의
package.json파일의contributes.languageModelTools섹션에 도구 항목을 추가합니다. -
도구에 고유한 이름 지정
속성 설명 이름확장 프로그램 구현 코드에서 도구를 참조하는 데 사용되는 도구의 고유 이름입니다. 이름을 {verb}_{noun}형식으로 지정합니다. 명명 규칙을 참조하세요.displayNameUI에 표시하는 데 사용되는 도구의 사용자 친화적인 이름입니다. -
도구를 에이전트와 함께 사용하거나
#을 사용하여 채팅 프롬프트에서 참조할 수 있다면 다음 속성을 추가하세요.사용자는 채팅 보기에서 도구를 활성화하거나 비활성화할 수 있으며, 이는 모델 컨텍스트 프로토콜(MCP) 도구의 경우와 유사합니다.
속성 설명 canBeReferencedInPrompt도구를 에이전트와 함께 사용하거나 채팅에서 참조할 수 있다면 true로 설정합니다.toolReferenceName사용자가 #을 통해 채팅 프롬프트에서 도구를 참조하는 데 사용하는 이름입니다.iconUI에서 도구에 표시될 아이콘입니다. userDescriptionUI에 표시하는 데 사용되는 도구의 사용자 친화적인 설명입니다. -
modelDescription에 자세한 설명을 추가합니다. 이 정보는 LLM이 도구를 어떤 맥락에서 사용해야 하는지 결정하는 데 사용됩니다.- 도구가 정확히 무엇을 하나요?
- 어떤 종류의 정보를 반환하나요?
- 언제 사용해야 하고 언제 사용하지 말아야 하나요?
- 도구의 중요한 제한 사항이나 제약 조건을 설명합니다.
-
도구가 입력 매개변수를 받는 경우, 도구의 입력 매개변수를 설명하는
inputSchema속성을 추가합니다.이 JSON 스키마는 도구가 입력으로 받는 속성 및 필수 여부를 포함하는 객체를 설명합니다. 파일 경로는 절대 경로여야 합니다.
각 매개변수가 무엇을 하는지, 그리고 도구의 기능과 어떻게 관련되는지 설명합니다.
-
도구가 사용 가능한 시점을 제어하기 위해
when절을 추가합니다.languageModelTools기여 지점을 사용하면 when 절을 사용하여 에이전트 모드에서 도구를 사용할 수 있는 시점이나 프롬프트에서 참조할 수 있는 시점을 제한할 수 있습니다. 예를 들어, 디버그 호출 스택 정보를 가져오는 도구는 사용자가 디버깅 중일 때만 사용할 수 있어야 합니다."contributes": { "languageModelTools": [ { "name": "chat-tools-sample_tabCount", ... "when": "debugState == 'running'" } ] }
예제 도구 정의
다음 예제는 탭 그룹에서 활성 탭 수를 계산하는 도구를 정의하는 방법을 보여줍니다.
"contributes": {
"languageModelTools": [
{
"name": "chat-tools-sample_tabCount",
"tags": [
"editors",
"chat-tools-sample"
],
"toolReferenceName": "tabCount",
"displayName": "Tab Count",
"modelDescription": "The number of active tabs in a tab group in VS Code.",
"userDescription": "Count the number of active tabs in a tab group.",
"canBeReferencedInPrompt": true,
"icon": "$(files)",
"inputSchema": {
"type": "object",
"properties": {
"tabGroup": {
"type": "number",
"description": "The index of the tab group to check. This is optional- if not specified, the active tab group will be checked.",
"default": 0
}
}
}
}
]
}
2. 도구 구현
다음 단계를 포함하여 언어 모델 API를 사용하여 언어 모델 도구를 구현합니다.
-
확장 프로그램이 활성화되면
vscode.lm.registerTool을 사용하여 도구를 등록합니다.package.json의name속성에 지정한 대로 도구 이름을 제공합니다.도구를 확장 프로그램에만 비공개로 하려면 도구 등록 단계를 건너뜁니다.
export function registerChatTools(context: vscode.ExtensionContext) { context.subscriptions.push( vscode.lm.registerTool('chat-tools-sample_tabCount', new TabCountTool()) ); } -
vscode.LanguageModelTool<>인터페이스를 구현하는 클래스를 만듭니다. -
prepareInvocation메서드에 도구 확인 메시지를 추가합니다.확장 프로그램의 도구에 대한 일반 확인 대화 상자가 항상 표시되지만, 도구는 확인 메시지를 사용자 지정할 수 있습니다. 사용자에게 도구가 수행하는 작업을 이해할 수 있도록 충분한 컨텍스트를 제공합니다. 메시지는 코드 블록이 포함된
MarkdownString일 수 있습니다.다음 예제는 탭 수 도구에 대한 확인 메시지를 제공하는 방법을 보여줍니다.
async prepareInvocation( options: vscode.LanguageModelToolInvocationPrepareOptions<ITabCountParameters>, _token: vscode.CancellationToken ) { const confirmationMessages = { title: 'Count the number of open tabs', message: new vscode.MarkdownString( `Count the number of open tabs?` + (options.input.tabGroup !== undefined ? ` in tab group ${options.input.tabGroup}` : '') ), }; return { invocationMessage: 'Counting the number of tabs', confirmationMessages, }; }prepareInvocation이undefined를 반환하면 일반 확인 메시지가 표시됩니다. 사용자는 특정 도구를 "항상 허용"하도록 선택할 수도 있습니다. -
도구 입력 매개변수를 설명하는 인터페이스를 정의합니다.
이 인터페이스는
vscode.LanguageModelTool클래스의invoke메서드에서 사용됩니다. 입력 매개변수는package.json의inputSchema에 정의된 JSON 스키마에 대해 유효성이 검사됩니다.다음 예제는 탭 수 도구의 인터페이스를 보여줍니다.
export interface ITabCountParameters { tabGroup?: number; } -
invoke메서드를 구현합니다. 이 메서드는 채팅 프롬프트를 처리하는 동안 언어 모델 도구가 호출될 때 호출됩니다.invoke메서드는options매개변수에서 도구 입력 매개변수를 받습니다. 매개변수는package.json의inputSchema에 정의된 JSON 스키마에 대해 유효성이 검사됩니다.오류가 발생하면 LLM에 의미 있는 메시지로 오류를 발생시킵니다. 선택적으로 LLM이 다음에 수행해야 할 작업에 대한 지침을 제공할 수 있습니다. 예를 들어, 다른 매개변수로 다시 시도하거나 다른 작업을 수행하는 것입니다.
다음 예제는 탭 수 도구의 구현을 보여줍니다. 도구의 결과는
vscode.LanguageModelToolResult유형의 인스턴스입니다.async invoke( options: vscode.LanguageModelToolInvocationOptions<ITabCountParameters>, _token: vscode.CancellationToken ) { const params = options.input; if (typeof params.tabGroup === 'number') { const group = vscode.window.tabGroups.all[Math.max(params.tabGroup - 1, 0)]; const nth = params.tabGroup === 1 ? '1st' : params.tabGroup === 2 ? '2nd' : params.tabGroup === 3 ? '3rd' : `${params.tabGroup}th`; return new vscode.LanguageModelToolResult([new vscode.LanguageModelTextPart(`There are ${group.tabs.length} tabs open in the ${nth} tab group.`)]); } else { const group = vscode.window.tabGroups.activeTabGroup; return new vscode.LanguageModelToolResult([new vscode.LanguageModelTextPart(`There are ${group.tabs.length} tabs open.`)]); } }
VS Code 확장 프로그램 샘플 리포지토리에서 언어 모델 도구를 구현하는 전체 소스 코드를 확인하세요.
도구 호출 흐름
사용자가 채팅 프롬프트를 보낼 때 다음 단계가 발생합니다.
-
Copilot은 사용자의 구성에 따라 사용 가능한 도구 목록을 결정합니다.
도구 목록은 기본 제공 도구, 확장 프로그램에서 등록한 도구 및 MCP 서버의 도구로 구성됩니다. 확장 프로그램 또는 MCP 서버(다이어그램의 녹색 부분)를 통해 에이전트 모드에 기여할 수 있습니다.
-
Copilot은 요청을 LLM에 보내고 프롬프트, 채팅 컨텍스트 및 고려할 도구 정의 목록을 제공합니다.
LLM은 응답을 생성하며, 여기에는 도구를 호출하라는 하나 이상의 요청이 포함될 수 있습니다.
-
필요한 경우 Copilot은 LLM에서 제공한 매개변수 값으로 제안된 도구를 호출합니다.
도구 응답으로 인해 도구 호출에 대한 추가 요청이 발생할 수 있습니다.
-
오류 또는 후속 도구 요청이 있는 경우 Copilot은 모든 도구 요청이 해결될 때까지 도구 호출 흐름을 반복합니다.
-
Copilot은 최종 응답을 사용자에게 반환하며, 여기에는 여러 도구의 응답이 포함될 수 있습니다.
명명 규칙 및 지침
-
명명: 도구 및 매개변수에 대해 명확하고 설명적인 이름을 작성합니다.
-
도구 이름: 고유해야 하며 의도를 명확하게 설명해야 합니다. 도구 이름은
{verb}_{noun}형식으로 구성합니다. 예:get_weather,get_azure_deployment또는get_terminal_output. -
매개변수 이름: 매개변수의 목적을 설명해야 합니다. 매개변수 이름은
{noun}형식으로 구성합니다. 예:destination_location,ticker또는file_name.
-
-
설명: 도구 및 매개변수에 대한 자세한 설명을 작성합니다.
- 도구가 수행하는 작업과 언제 사용해야 하고 사용하지 말아야 하는지 설명합니다. 예: "이 도구는 주어진 위치의 날씨를 검색합니다."
- 각 매개변수가 무엇을 하는지, 그리고 도구의 기능과 어떻게 관련되는지 설명합니다. 예: "
destination_location매개변수는 날씨를 검색할 위치를 지정합니다. 유효한 위치 이름 또는 좌표여야 합니다." - 도구의 중요한 제한 사항이나 제약 조건을 설명합니다. 예: "이 도구는 미국 내 위치의 날씨 데이터만 검색합니다. 다른 지역에서는 작동하지 않을 수 있습니다."
-
사용자 확인: 도구 호출에 대한 확인 메시지를 제공합니다. 확장 프로그램의 도구에 대한 일반 확인 대화 상자가 항상 표시되지만, 도구는 확인 메시지를 사용자 지정할 수 있습니다. 사용자에게 도구가 수행하는 작업을 이해할 수 있도록 충분한 컨텍스트를 제공합니다.
-
오류 처리: 오류가 발생하면 LLM에 의미 있는 메시지로 오류를 발생시킵니다. 선택적으로 LLM이 다음에 수행해야 할 작업에 대한 지침을 제공할 수 있습니다. 예를 들어, 다른 매개변수로 다시 시도하거나 다른 작업을 수행하는 것입니다.
도구 작성을 위한 더 많은 모범 사례는 OpenAI 설명서의 OpenAI 설명서와 Anthropic 설명서에서 확인하세요.