채팅 참가자 API

채팅 참가자는 사용자가 VS Code에서 채팅을 도메인별 전문가로 확장할 수 있도록 하는 특수 어시스턴트입니다. 사용자는 @ 멘션을 통해 채팅 참가자를 호출하며, 참가자는 사용자의 자연어 프롬프트를 처리할 책임이 있습니다.

이 확장 프로그램 가이드에서는 채팅 참가자 API를 사용하여 채팅 참가자를 만드는 방법을 알아봅니다.

VS Code에는 @vscode, @terminal, @workspace와 같은 여러 내장 채팅 참가자가 있습니다. 이 참가자들은 해당 도메인에 대한 질문에 답변하도록 최적화되어 있습니다.

채팅 참가자는 LLM이 사용자 채팅 프롬프트를 해결하는 데 필요한 단계를 조정할 때 호출되는 언어 모델 도구와 다릅니다. 채팅 참가자는 사용자 프롬프트를 수신하고 필요한 작업을 직접 조정합니다.

확장 프로그램에 채팅 참가자를 구현해야 하는 이유는 무엇인가요?

확장 프로그램에 채팅 참가자를 구현하면 다음과 같은 여러 이점이 있습니다.

• 특화된 도메인별 지식과 전문 지식으로 채팅을 확장하세요. 예를 들어, 내장 @vscode 참가자는 VS Code 및 해당 확장 프로그램 API에 대한 지식을 보유하고 있습니다.
• 전체 사용자 채팅 프롬프트 및 응답을 관리하여 대화를 소유하세요.
• 광범위한 확장 프로그램 API를 사용하여 VS Code와 깊이 통합하세요. 예를 들어, 디버거 API를 사용하여 현재 디버깅 컨텍스트를 가져오고 이를 도구 기능의 일부로 사용할 수 있습니다.
• Visual Studio Marketplace를 통해 채팅 참가자를 배포하고 배포하여 사용자에게 안정적이고 원활한 경험을 제공하세요. 사용자는 별도의 설치 및 업데이트 프로세스가 필요하지 않습니다.

자율적인 코딩 세션의 일부로 자동으로 호출될 수 있는 도메인별 기능을 제공하려면 언어 모델 도구 또는 MCP 서버 구현을 고려할 수 있습니다. 다양한 옵션과 어떤 접근 방식을 사용할지 결정하는 방법에 대한 자세한 내용은 AI 확장성 개요를 참조하세요.

채팅 사용자 경험의 일부

다음 스크린샷은 샘플 확장 프로그램의 Visual Studio Code 채팅 환경에서 다양한 채팅 개념을 보여줍니다.

1. @ 구문을 사용하여 @cat 채팅 참가자를 호출합니다.
2. / 구문을 사용하여 /teach 명령을 호출합니다.
3. 사용자가 제공한 쿼리, 사용자 프롬프트라고도 합니다.
4. 아이콘 및 참가자 fullName은 Copilot이 @cat 채팅 참가자를 사용하고 있음을 나타냅니다.
5. @cat에서 제공한 Markdown 응답
6. Markdown 응답에 포함된 코드 조각
7. @cat 응답에 포함된 버튼, 이 버튼은 VS Code 명령을 호출합니다.
8. 채팅 참가자에서 제공하는 제안된 후속 질문
9. 채팅 참가자의 description 속성에서 제공한 자리 표시자 텍스트가 있는 채팅 입력 필드

채팅 참가자 만들기

채팅 참가자를 구현하는 것은 다음 부분으로 구성됩니다.

1. 확장 프로그램의 package.json 파일에서 채팅 참가자를 정의합니다.
2. 사용자의 채팅 프롬프트를 처리하고 응답을 반환하는 요청 처리기를 구현합니다.
3. (선택 사항) 일반적인 작업에 대한 바로 가기 표기법을 제공하기 위해 채팅 슬래시 명령을 구현합니다.
4. (선택 사항) 제안된 후속 질문을 정의합니다.
5. (선택 사항) 사용자가 명시적으로 언급하지 않고도 VS Code가 적절한 채팅 참가자에게 채팅 요청을 자동으로 라우팅하는 참가자 감지를 구현합니다.

기본 예제 프로젝트로 시작할 수 있습니다.

1. 채팅 참가자 등록

채팅 확장 프로그램을 만드는 첫 번째 단계는 다음 속성을 사용하여 package.json에 등록하는 것입니다.

• id: package.json 파일에 정의된 채팅 참가자의 고유 식별자입니다.
• name: 채팅에서 @ 멘션에 사용되는 채팅 참가자의 짧은 이름입니다.
• fullName: 응답의 제목 영역에 표시되는 채팅 참가자의 전체 이름입니다.
• description: 채팅 입력 필드의 자리 표시자 텍스트로 사용되는 채팅 참가자의 목적에 대한 간략한 설명입니다.
• isSticky: 응답 후 채팅 입력 필드에 채팅 참가자가 지속되는지 여부를 나타내는 부울 값입니다.

"contributes": {
        "chatParticipants": [
            {
                "id": "chat-sample.my-participant",
                "name": "my-participant",
                "fullName": "My Participant",
                "description": "What can I teach you?",
                "isSticky": true
            }
        ]
}

기존 채팅 참가자와 일치하도록 소문자 name을 사용하고 fullName에는 제목 대소문자를 사용하는 것이 좋습니다. 채팅 참가자 이름 지정 규칙에 대한 자세한 정보를 얻으세요.

2. 요청 처리기 구현

채팅 참가자 API를 사용하여 채팅 참가자를 구현합니다. 이는 다음 단계로 구성됩니다.

1. 확장 프로그램이 활성화되면 vscode.chat.createChatParticipant으로 참가자를 만듭니다.

   package.json에서 정의한 ID와 다음 단계에서 구현할 요청 처리기에 대한 참조를 제공합니다.

   export function activate(context: vscode.ExtensionContext) {
     // Register the chat participant and its request handler
     const cat = vscode.chat.createChatParticipant('chat-sample.my-participant', handler);
   
     // Optionally, set some properties for @cat
     cat.iconPath = vscode.Uri.joinPath(context.extensionUri, 'cat.jpeg');
   
     // Add the chat request handler here
   }
   

2. activate 함수에서 vscode.ChatRequestHandler 요청 처리기를 정의합니다.

   요청 처리기는 VS Code 채팅 보기에서 사용자의 채팅 요청을 처리할 책임이 있습니다. 사용자가 채팅 입력 필드에 프롬프트를 입력할 때마다 채팅 요청 처리기가 호출됩니다.

   const handler: vscode.ChatRequestHandler = async (
     request: vscode.ChatRequest,
     context: vscode.ChatContext,
     stream: vscode.ChatResponseStream,
     token: vscode.CancellationToken
   ): Promise<ICatChatResult> => {
     // Chat request handler implementation goes here
   };
   

3. vscode.ChatRequest에서 사용자 의도를 결정합니다.

   사용자 요청의 의도를 결정하기 위해 vscode.ChatRequest 매개 변수를 참조하여 사용자 프롬프트 텍스트, 명령 및 채팅 위치에 액세스할 수 있습니다.

   선택적으로, 기존 논리를 사용하는 대신 언어 모델을 활용하여 사용자 의도를 결정할 수 있습니다. request 개체의 일부로 사용자가 채팅 모델 드롭다운에서 선택한 언어 모델 인스턴스를 얻습니다. 확장 프로그램에서 언어 모델 API를 사용하는 방법을 알아봅니다.

   다음 코드 스니펫은 명령을 먼저 사용한 다음 사용자 프롬프트를 사용하여 사용자 의도를 결정하는 기본 구조를 보여줍니다.

   const handler: vscode.ChatRequestHandler = async (
     request: vscode.ChatRequest,
     context: vscode.ChatContext,
     stream: vscode.ChatResponseStream,
     token: vscode.CancellationToken
   ): Promise<ICatChatResult> => {
     // Test for the `teach` command
     if (request.command == 'teach') {
       // Add logic here to handle the teaching scenario
       doTeaching(request.prompt, request.variables);
     } else {
       // Determine the user's intent
       const intent = determineUserIntent(request.prompt, request.variables, request.model);
   
       // Add logic here to handle other scenarios
     }
   };
   

4. 사용자 요청을 처리하기 위한 로직을 추가합니다.

   종종 채팅 확장 프로그램은 request.model 언어 모델 인스턴스를 사용하여 요청을 처리합니다. 이 경우 사용자 의도에 맞게 언어 모델 프롬프트를 조정할 수 있습니다.

   또는 백엔드 서비스를 호출하거나, 기존 프로그래밍 논리를 사용하거나, 이 모든 옵션을 조합하여 확장 프로그램 논리를 구현할 수 있습니다. 예를 들어, 웹 검색을 호출하여 추가 정보를 수집하고 이를 언어 모델에 컨텍스트로 제공할 수 있습니다.

   현재 요청을 처리하는 동안 이전 채팅 메시지를 참조해야 할 수 있습니다. 예를 들어, 이전 응답에서 C# 코드 조각이 반환된 경우 사용자의 현재 요청은 "Python으로 코드를 제공하세요"일 수 있습니다. 채팅 메시지 기록을 사용하는 방법을 알아봅니다.

   채팅 입력의 위치(채팅 보기, 빠른 채팅, 인라인 채팅)에 따라 요청을 다르게 처리하려면 vscode.ChatRequest의 location 속성을 사용할 수 있습니다. 예를 들어, 사용자가 터미널 인라인 채팅에서 요청을 보내면 셸 명령을 조회할 수 있습니다. 반면에 사용자가 채팅 보기를 사용하면 더 상세한 응답을 반환할 수 있습니다.

5. 사용자에게 채팅 응답을 반환합니다.

   요청을 처리한 후에는 채팅 보기에서 사용자에게 응답을 반환해야 합니다. 스트리밍을 사용하여 사용자 쿼리에 응답할 수 있습니다.

   응답에는 Markdown, 이미지, 참조, 진행률, 버튼 및 파일 트리와 같은 다양한 콘텐츠 유형이 포함될 수 있습니다.

   

   확장 프로그램은 다음과 같은 방법으로 응답 스트림을 사용할 수 있습니다.

   stream.progress('Picking the right topic to teach...');
   stream.markdown(`\`\`\`typescript
   const myStack = new Stack();
   myStack.push(1); // pushing a number on the stack (or let's say, adding a fish to the stack)
   myStack.push(2); // adding another fish (number 2)
   console.log(myStack.pop()); // eating the top fish, will output: 2
   \`\`\`
   So remember, Code Kitten, in a stack, the last fish in is the first fish out - which we tech cats call LIFO (Last In, First Out).`);
   
   stream.button({
     command: 'cat.meow',
     title: vscode.l10n.t('Meow!'),
     arguments: []
   });
   

   지원되는 채팅 응답 출력 유형에 대한 자세한 정보를 얻으세요.

   실제로 확장 프로그램은 일반적으로 언어 모델에 요청을 보냅니다. 언어 모델에서 응답을 받으면 추가로 처리하고 사용자에게 스트리밍할 것이 있는지 결정할 수 있습니다. VS Code 채팅 API는 스트리밍 기반이며 스트리밍 언어 모델 API와 호환됩니다. 이를 통해 확장 프로그램은 원활한 사용자 경험을 목표로 진행률과 결과를 지속적으로 보고할 수 있습니다. 언어 모델 API를 사용하는 방법을 알아봅니다.

3. 슬래시 명령 등록

채팅 참가자는 확장 프로그램에서 제공하는 특정 기능에 대한 바로 가기인 슬래시 명령을 제공할 수 있습니다. 사용자는 / 구문(예: /explain)을 사용하여 채팅에서 슬래시 명령을 참조할 수 있습니다.

질문에 답변할 때 한 가지 작업은 사용자 의도를 결정하는 것입니다. 예를 들어, VS Code는 Node.js Express Pug TypeScript로 새 작업 영역 만들기가 새 프로젝트를 원한다는 것을 추론할 수 있지만, @workspace /new Node.js Express Pug TypeScript는 더 명확하고 간결하며 입력 시간을 절약합니다. 채팅 입력 필드에 /를 입력하면 VS Code는 등록된 명령 목록과 해당 설명을 제공합니다.

채팅 참가자는 package.json에 추가하여 설명과 함께 슬래시 명령을 제공할 수 있습니다.

"contributes": {
    "chatParticipants": [
        {
            "id": "chat-sample.cat",
            "name": "cat",
            "fullName": "Cat",
            "description": "Meow! What can I teach you?",
            "isSticky": true,
            "commands": [
                {
                    "name": "teach",
                    "description": "Pick at random a computer science concept then explain it in purfect way of a cat"
                },
                {
                    "name": "play",
                    "description": "Do whatever you want, you are a cat after all"
                }
            ]
        }
    ]
}

슬래시 명령 이름 지정 규칙에 대한 자세한 정보를 얻으세요.

4. 후속 요청 등록

각 채팅 요청 후 VS Code는 후속 공급자를 호출하여 사용자에게 표시할 후속 질문을 가져옵니다. 그러면 사용자는 후속 질문을 선택하고 즉시 채팅 확장 프로그램으로 보낼 수 있습니다. ChatFollowupProvider API를 사용하여 ChatFollowup 유형의 후속 프롬프트를 등록합니다.

다음 코드 스니펫은 채팅 확장 프로그램에서 후속 요청을 등록하는 방법을 보여줍니다.

cat.followupProvider = {
    provideFollowups(result: ICatChatResult, context: vscode.ChatContext, token: vscode.CancellationToken) {
        if (result.metadata.command === 'teach') {
            return [{
                prompt: 'let us play',
                label: vscode.l10n.t('Play with the cat')
            } satisfies vscode.ChatFollowup];
        }
    }
};

5. 참가자 감지 구현

채팅 참가자를 자연어로 더 쉽게 사용하려면 참가자 감지를 구현할 수 있습니다. 참가자 감지는 프롬프트에서 참가자를 명시적으로 언급할 필요 없이 사용자의 질문을 적합한 참가자로 자동으로 라우팅하는 방법입니다. 예를 들어, 사용자가 "내 프로젝트에 로그인 페이지를 추가하려면 어떻게 해야 하나요?"라고 질문하면, 사용자의 프로젝트에 대한 질문에 답변할 수 있는 @workspace 참가자로 질문이 자동으로 라우팅됩니다.

VS Code는 채팅 참가자 설명과 예제를 사용하여 어떤 참가자로 채팅 프롬프트를 라우팅할지 결정합니다. 이 정보는 확장 프로그램 package.json 파일의 disambiguation 속성에 지정할 수 있습니다. disambiguation 속성에는 설명과 예제가 포함된 감지 카테고리 목록이 포함되어 있습니다.

참가자 수준 전체, 특정 명령 또는 둘 다의 조합에 대해 참가자 감지를 정의할 수 있습니다.

다음 코드 스니펫은 참가자 수준에서 참가자 감지를 구현하는 방법을 보여줍니다.

"contributes": {
    "chatParticipants": [
        {
            "id": "chat-sample.cat",
            "fullName": "Cat",
            "name": "cat",
            "description": "Meow! What can I teach you?",

            "disambiguation": [
                {
                    "category": "cat",
                    "description": "The user wants to learn a specific computer science topic in an informal way.",
                    "examples": [
                        "Teach me C++ pointers using metaphors",
                        "Explain to me what is a linked list in a simple way",
                        "Can you explain to me what is a function in programming?"
                    ]
                }
            ]
        }
    ]
}

마찬가지로, commands 속성의 하나 이상의 항목에 disambiguation 속성을 추가하여 명령 수준에서 참가자 감지를 구성할 수도 있습니다.

확장 프로그램의 참가자 감지 정확도를 높이기 위해 다음 지침을 적용하세요.

• 구체적으로 작성하세요: 설명과 예시는 다른 참가자와의 충돌을 피하기 위해 가능한 한 구체적이어야 합니다. 참가자 및 명령 정보에서 일반적인 용어 사용을 피하세요.
• 예시 사용: 예시는 참가자에 적합한 질문 종류를 대표해야 합니다. 동의어 및 변형을 사용하여 광범위한 사용자 쿼리를 다루세요.
• 자연어 사용: 설명과 예시는 참가자를 사용자에게 설명하는 것처럼 자연어로 작성해야 합니다.
• 감지 테스트: 예시 질문의 다양한 변형으로 참가자 감지를 테스트하고 내장 채팅 참가자와 충돌이 없는지 확인하세요.

채팅 메시지 기록 사용

참가자는 현재 채팅 세션의 메시지 기록에 액세스할 수 있습니다. 참가자는 자신이 언급된 메시지만 액세스할 수 있습니다. history 항목은 ChatRequestTurn 또는 ChatResponseTurn입니다. 예를 들어, 다음 코드 스니펫을 사용하여 현재 채팅 세션에서 참가자에게 보낸 모든 이전 요청을 검색할 수 있습니다.

const previousMessages = context.history.filter(h => h instanceof vscode.ChatRequestTurn);

기록은 자동으로 프롬프트에 포함되지 않으며, 참가자가 메시지를 언어 모델에 전달할 때 기록을 추가 컨텍스트로 추가할지 여부를 결정해야 합니다.

지원되는 채팅 응답 출력 유형

채팅 요청에 응답하려면 ChatRequestHandler의 ChatResponseStream 매개 변수를 사용합니다.

다음 목록은 채팅 보기에서 채팅 응답의 출력 유형을 제공합니다. 채팅 응답은 여러 다른 출력 유형을 결합할 수 있습니다.

• Markdown

  Markdown 텍스트, 일반 텍스트 또는 이미지를 렌더링합니다. CommonMark 사양의 일부인 모든 Markdown 구문을 사용할 수 있습니다. ChatResponseStream.markdown 메서드를 사용하고 Markdown 텍스트를 제공하세요.

  예제 코드 스니펫

  // Render Markdown text
  stream.markdown('# This is a title \n');
  stream.markdown('This is stylized text that uses _italics_ and **bold**. ');
  stream.markdown('This is a [link](https://vscode.gisul.kr).\n\n');
  stream.markdown('![VS Code](https://vscode.gisul.kr/assets/favicon.ico)');
  

• 코드 블록

  IntelliSense, 코드 서식 및 코드에 적용할 수 있는 대화형 컨트롤을 지원하는 코드 블록을 렌더링합니다. 코드 블록을 표시하려면 ChatResponseStream.markdown 메서드를 사용하고 백틱을 사용하여 코드 블록에 대한 Markdown 구문을 적용합니다.

  예제 코드 스니펫

  // Render a code block that enables users to interact with
  stream.markdown('```bash\n');
  stream.markdown('```ls -l\n');
  stream.markdown('```');
  

• 명령 링크

  채팅 응답에 사용자가 VS Code 명령을 호출하도록 선택할 수 있는 인라인 링크를 렌더링합니다. 명령 링크를 표시하려면 ChatResponseStream.markdown 메서드를 사용하고 링크에 대한 Markdown 구문 [link text](command:commandId)를 사용하며, 여기서 URL에 명령 ID를 제공합니다. 예를 들어, 다음 링크는 명령 팔레트를 엽니다: [Command Palette](command:workbench.action.showCommands).

  명령 삽입을 방지하려면 서비스에서 Markdown 텍스트를 로드할 때 isTrusted 속성이 신뢰할 수 있는 VS Code 명령 ID 목록으로 설정된 vscode.MarkdownString 개체를 사용해야 합니다. 이 속성은 명령 링크가 작동하도록 하는 데 필요합니다. isTrusted 속성이 설정되지 않았거나 명령이 목록에 없으면 명령 링크가 작동하지 않습니다.

  예제 코드 스니펫

  // Use command URIs to link to commands from Markdown
  let markdownCommandString: vscode.MarkdownString = new vscode.MarkdownString(
    `[Use cat names](command:${CAT_NAMES_COMMAND_ID})`
  );
  markdownCommandString.isTrusted = { enabledCommands: [CAT_NAMES_COMMAND_ID] };
  
  stream.markdown(markdownCommandString);
  

  명령이 인수를 사용하는 경우 먼저 인수를 JSON으로 인코딩한 다음 URI 구성 요소로 JSON 문자열을 인코딩해야 합니다. 그런 다음 인코딩된 인수를 쿼리 문자열로 명령 링크에 추가합니다.

  // Encode the command arguments
  const encodedArgs = encodeURIComponent(JSON.stringify(args));
  
  // Use command URIs with arguments to link to commands from Markdown
  let markdownCommandString: vscode.MarkdownString = new vscode.MarkdownString(
    `[Use cat names](command:${CAT_NAMES_COMMAND_ID}?${encodedArgs})`
  );
  markdownCommandString.isTrusted = { enabledCommands: [CAT_NAMES_COMMAND_ID] };
  
  stream.markdown(markdownCommandString);
  

• 명령 버튼

  VS Code 명령을 호출하는 버튼을 렌더링합니다. 명령은 내장 명령이거나 확장 프로그램에서 정의한 명령일 수 있습니다. ChatResponseStream.button 메서드를 사용하고 버튼 텍스트와 명령 ID를 제공합니다.

  예제 코드 스니펫

  // Render a button to trigger a VS Code command
  stream.button({
    command: 'my.command',
    title: vscode.l10n.t('Run my command')
  });
  

• 파일 트리

  사용자가 개별 파일을 미리 볼 수 있는 파일 트리 컨트롤을 렌더링합니다. 예를 들어, 새 작업 영역을 만들려고 할 때 작업 영역 미리 보기를 표시합니다. ChatResponseStream.filetree 메서드를 사용하고 파일 트리 요소 배열과 파일의 기본 위치(폴더)를 제공합니다.

  예제 코드 스니펫

  // Create a file tree instance
  var tree: vscode.ChatResponseFileTree[] = [
    {
      name: 'myworkspace',
      children: [{ name: 'README' }, { name: 'app.js' }, { name: 'package.json' }]
    }
  ];
  
  // Render the file tree control at a base location
  stream.filetree(tree, baseLocation);
  

• 진행률 메시지

  오래 실행되는 작업 중에 진행률 메시지를 렌더링하여 사용자에게 중간 피드백을 제공합니다. 예를 들어, 다단계 작업의 각 단계 완료를 보고합니다. ChatResponseStream.progress 메서드를 사용하고 메시지를 제공합니다.

  예제 코드 스니펫

  // Render a progress message
  stream.progress('Connecting to the database.');
  

• 참조

  외부 URL 또는 편집기 위치에 대한 참조를 참조 목록에 추가하여 어떤 정보를 컨텍스트로 사용하는지 표시합니다. ChatResponseStream.reference 메서드를 사용하고 참조 위치를 제공합니다.

  예제 코드 스니펫

  const fileUri: vscode.Uri = vscode.Uri.file('/path/to/workspace/app.js'); // On Windows, the path should be in the format of 'c:\\path\\to\\workspace\\app.js'
  const fileRange: vscode.Range = new vscode.Range(0, 0, 3, 0);
  const externalUri: vscode.Uri = vscode.Uri.parse('https://vscode.gisul.kr');
  
  // Add a reference to an entire file
  stream.reference(fileUri);
  
  // Add a reference to a specific selection within a file
  stream.reference(new vscode.Location(fileUri, fileRange));
  
  // Add a reference to an external URL
  stream.reference(externalUri);
  

• 인라인 참조

  URI 또는 편집기 위치에 대한 인라인 참조를 추가합니다. ChatResponseStream.anchor 메서드를 사용하고 앵커 위치와 선택적 제목을 제공합니다. 기호(예: 클래스 또는 변수)를 참조하려면 편집기에서 위치를 사용합니다.

  예제 코드 스니펫

  const symbolLocation: vscode.Uri = vscode.Uri.parse('location-to-a-symbol');
  
  // Render an inline anchor to a symbol in the workspace
  stream.anchor(symbolLocation, 'MySymbol');
  

중요: 이미지와 링크는 신뢰할 수 있는 도메인 목록에 속하는 경우에만 사용할 수 있습니다. VS Code의 링크 보호에 대한 자세한 정보를 얻으세요.

도구 호출 구현

사용자 요청에 응답하기 위해 채팅 확장 프로그램은 언어 모델 도구를 호출할 수 있습니다. 언어 모델 도구와 도구 호출 흐름에 대해 자세히 알아보세요.

다음 두 가지 방법으로 도구 호출을 구현할 수 있습니다.

• 채팅 확장 프로그램에서 도구 호출 프로세스를 단순화하기 위해 @vscode/chat-extension-utils 라이브러리를 사용합니다.
• 도구 호출 자체를 구현하여 도구 호출 프로세스를 더 많이 제어합니다. 예를 들어, 추가 유효성 검사를 수행하거나 LLM에 보내기 전에 특정 방식으로 도구 응답을 처리합니다.

채팅 확장 프로그램 라이브러리로 도구 호출 구현

채팅 확장 프로그램에서 도구 호출 프로세스를 단순화하기 위해 @vscode/chat-extension-utils 라이브러리를 사용할 수 있습니다.

채팅 참가자의 vscode.ChatRequestHandler 함수에서 도구 호출을 구현합니다.

1. 현재 채팅 컨텍스트에 적합한 도구를 결정합니다. vscode.lm.tools를 사용하여 모든 사용 가능한 도구에 액세스할 수 있습니다.

   다음 코드 스니펫은 특정 태그가 있는 도구만 필터링하는 방법을 보여줍니다.

   const tools =
     request.command === 'all'
       ? vscode.lm.tools
       : vscode.lm.tools.filter(tool => tool.tags.includes('chat-tools-sample'));
   

2. sendChatParticipantRequest를 사용하여 요청 및 도구 정의를 LLM에 보냅니다.

   const libResult = chatUtils.sendChatParticipantRequest(
     request,
     chatContext,
     {
       prompt: 'You are a cat! Answer as a cat.',
       responseStreamOptions: {
         stream,
         references: true,
         responseText: true
       },
       tools
     },
     token
   );
   

   ChatHandlerOptions 개체에는 다음 속성이 있습니다.

   • prompt: (선택 사항) 채팅 참가자 프롬프트에 대한 지침입니다.
   • model: (선택 사항) 요청에 사용할 모델입니다. 지정하지 않으면 채팅 컨텍스트의 모델이 사용됩니다.
   • tools: (선택 사항) 요청에서 고려할 도구 목록입니다.
   • requestJustification: (선택 사항) 요청이 이루어진 이유를 설명하는 문자열입니다.
   • responseStreamOptions: (선택 사항) sendChatParticipantRequest가 응답을 VS Code로 스트리밍하도록 합니다. 선택적으로 참조 및/또는 응답 텍스트를 사용하도록 설정할 수도 있습니다.

3. LLM에서 결과를 반환합니다. 오류 세부 정보 또는 도구 호출 메타데이터가 포함될 수 있습니다.

   return await libResult.result;
   

이 도구 호출 샘플의 전체 소스 코드는 VS Code 확장 샘플 리포지토리에서 사용할 수 있습니다.

도구 호출 자체 구현

더 고급 시나리오의 경우 도구 호출을 자체적으로 구현할 수도 있습니다. 선택적으로 @vscode/prompt-tsx 라이브러리를 사용하여 LLM 프롬프트를 제작할 수 있습니다. 도구 호출을 자체적으로 구현하면 도구 호출 프로세스를 더 많이 제어할 수 있습니다. 예를 들어, 추가 유효성 검사를 수행하거나 LLM에 보내기 전에 특정 방식으로 도구 응답을 처리합니다.

VS Code 확장 샘플 리포지토리에서 prompt-tsx를 사용하여 도구 호출을 구현하는 전체 소스 코드를 확인하세요.

성공 측정

Unhelpful 사용자 피드백 이벤트와 참가자가 처리한 총 요청 수에 대한 원격 분석 로깅을 추가하여 참가자의 성공을 측정하는 것이 좋습니다. 초기 참가자 성공 메트릭은 다음과 같이 정의할 수 있습니다: unhelpful_feedback_count / total_requests.

const logger = vscode.env.createTelemetryLogger({
  // telemetry logging implementation goes here
});

cat.onDidReceiveFeedback((feedback: vscode.ChatResultFeedback) => {
  // Log chat result feedback to be able to compute the success metric of the participant
  logger.logUsage('chatResultFeedback', {
    kind: feedback.kind
  });
});

채팅 응답에 대한 기타 사용자 상호 작용은 긍정적인 메트릭으로 측정해야 합니다(예: 사용자가 채팅 응답에서 생성된 버튼을 선택하는 것). AI는 비결정적 기술이므로 원격 분석을 사용하여 성공을 측정하는 것이 중요합니다. 실험을 실행하고, 측정하고, 참가자를 반복적으로 개선하여 좋은 사용자 경험을 보장하세요.

지침 및 규칙

지침

채팅 참가자는 단순한 질문-답변 봇이어서는 안 됩니다. 채팅 참가자를 구축할 때 창의력을 발휘하고 기존 VS Code API를 사용하여 VS Code에서 풍부한 통합을 만드세요. 사용자들은 응답의 버튼, 채팅에서 참가자로 사용자를 안내하는 메뉴 항목과 같이 풍부하고 편리한 상호 작용을 좋아합니다. AI가 사용자를 도울 수 있는 실제 시나리오를 생각해 보세요.

모든 확장 프로그램이 채팅 참가자를 제공하는 것이 의미 있는 것은 아닙니다. 채팅에 참가자가 너무 많으면 사용자 경험이 저하될 수 있습니다. 채팅 참가자는 언어 모델에 대한 지침을 포함하여 전체 프롬프트를 제어하려는 경우에 가장 좋습니다. 신중하게 작성된 Copilot 시스템 메시지를 재사용하고 다른 참가자에게 컨텍스트를 제공할 수 있습니다.

예를 들어, 언어 확장 프로그램(C++ 확장 프로그램 등)은 다양한 다른 방식으로 기여할 수 있습니다.

• 언어 서비스 인텔리전스를 사용자 쿼리에 제공하는 도구를 제공하세요. 예를 들어, C++ 확장 프로그램은 #cpp 도구를 작업 영역의 C++ 상태로 확인할 수 있습니다. 이렇게 하면 Copilot 언어 모델에 적절한 C++ 컨텍스트를 제공하여 C++에 대한 Copilot 답변의 품질을 향상시킬 수 있습니다.
• 언어 모델을 사용하고 선택적으로 기존 언어 서비스 지식과 결합하여 훌륭한 사용자 경험을 제공하는 스마트 작업을 제공하세요. 예를 들어, C++는 이미 새 메서드에 대한 적절한 기본 이름을 생성하는 언어 모델을 사용하는 "메서드로 추출" 스마트 작업을 제공할 수 있습니다.

채팅 확장 프로그램은 비용이 많이 드는 작업을 시작하거나 실행 취소할 수 없는 것을 편집하거나 삭제하려고 할 때 사용자에게 명시적으로 동의를 구해야 합니다. 훌륭한 사용자 경험을 위해 확장 프로그램이 여러 채팅 참가자를 제공하는 것을 권장하지 않습니다. 확장 프로그램당 최대 하나의 채팅 참가자는 UI에 잘 확장되는 간단한 모델입니다.

채팅 참가자 이름 지정 규칙

사용자 대면 요소(속성, 채팅 응답 또는 채팅 사용자 인터페이스 등)에서 채팅 참가자를 참조할 때 API 이름이므로 참가자라는 용어를 사용하지 않는 것이 좋습니다. 예를 들어, @cat 확장 프로그램은 "GitHub Copilot용 Cat 확장 프로그램"이라고 불릴 수 있습니다.

슬래시 명령 이름 지정 규칙

확장 프로그램 게시

AI 확장 프로그램을 만든 후에는 Visual Studio Marketplace에 확장 프로그램을 게시할 수 있습니다.

• VS Marketplace에 게시하기 전에 Microsoft AI 도구 및 관행 지침을 읽는 것이 좋습니다. 이러한 지침은 AI 기술의 책임감 있는 개발 및 사용을 위한 모범 사례를 제공합니다.
• VS Marketplace에 게시함으로써 확장 프로그램은 GitHub Copilot 확장성 허용 개발 및 사용 정책을 준수합니다.
• 확장 프로그램 게시에 설명된 대로 Marketplace에 업로드하세요.
• 확장 프로그램이 이미 채팅 외의 기능을 제공하는 경우, 확장 프로그램 매니페스트에서 GitHub Copilot에 대한 확장 프로그램 종속성을 도입하지 않는 것이 좋습니다. 이렇게 하면 GitHub Copilot을 사용하지 않는 확장 프로그램 사용자가 GitHub Copilot을 설치하지 않고도 채팅 외 기능을 사용할 수 있습니다.

GitHub 앱을 통한 GitHub Copilot 확장

또는 GitHub 앱을 만들어 채팅 보기에서 채팅 참가자를 제공함으로써 GitHub Copilot을 확장할 수 있습니다. GitHub 앱은 서비스로 지원되며 github.com, Visual Studio 또는 VS Code와 같은 모든 GitHub Copilot 표면에서 작동합니다. 반면에 GitHub 앱은 VS Code API에 대한 전체 액세스 권한이 없습니다. GitHub 앱을 통해 GitHub Copilot을 확장하는 방법에 대한 자세한 내용은 GitHub 설명서를 참조하세요.

언어 모델 사용

채팅 참가자는 다양한 방식으로 언어 모델을 사용할 수 있습니다. 일부 참가자는 사용자 지정 프롬프트에 대한 답변을 얻기 위해 언어 모델만 사용합니다(예: 샘플 채팅 참가자). 다른 참가자는 더 발전된 기능을 제공하며 언어 모델의 도움으로 여러 도구를 호출하는 자율 에이전트처럼 작동합니다. 이러한 고급 참가자의 예는 작업 영역에 대해 알고 해당 작업 영역에 대한 질문에 답변할 수 있는 내장 @workspace입니다. 내부적으로 @workspace은 GitHub의 지식 그래프, 의미론적 검색, 로컬 코드 인덱스 및 VS Code의 언어 서비스를 결합한 여러 도구로 구동됩니다.

관련 콘텐츠

• 채팅 참가자 API 참조
• 확장 프로그램에서 언어 모델 API 사용
• 언어 모델 도구 제공