모바일 및 사용자 지정 앱에 Copilot 추가

아티클
04/22/2024

중요

Power Virtual Agents 기능 및 특징은 생성 AI에 대한 막대한 투자와 Microsoft Copilot 전반의 향상된 통합에 따라 이제 Microsoft Copilot Studio의 일부가 되었습니다.

문서 및 교육 콘텐츠를 업데이트하는 동안 일부 문서와 스크린샷에서는 Power Virtual Agents을 참조할 수 있습니다.

Copilot을 사용자 지정 앱에 연결하여 앱 사용자가 앱 내에서 Copilot과 직접 상호 작용할 수 있습니다.

대부분의 경우 사용자 지정 앱은 웹 기반 앱이거나 기본 앱이거나 비즈니스에 필요한 다른 서비스에 대한 어댑터인 모바일 장치 앱입니다.

앱이 웹 기반 앱인지 기본 앱인지에 따라 모바일 앱에 연결하는 절차는 다릅니다.

Copilot을 웹 기반 앱에 연결하려면 코드 조각을 앱에 복사하면 되므로 비교적 간단합니다. 그러나 웹 기반 앱과 기본 또는 사용자 지정 앱 모두 Copilot을 앱에 완전히 통합하려면 상당한 개발자 전문 지식이 필요합니다. 두 절차 다 이 문서에 설명되어 있습니다.

전제 조건

.NET Core SDK 버전 2.1.
NuGet 패키지 Microsoft.Bot.Connector.DirectLine.
앱에 연결하려는 Copilot Studio에서 만든 Copilot.

Copilot을 웹 기반 앱에 연결

Copilot Studio의 탐색 메뉴에서 설정 아래의 채널을 선택합니다.
모바일 앱 타일을 선택하여 구성 창을 엽니다.
웹 기반 앱 섹션 아래 코드를 복사하고 앱 개발자에게 제공하여 웹 기반 앱에 추가하십시오.

Copilot을 기본 또는 사용자 지정 앱에 연결

팁

이 섹션에서는 모바일 앱에 연결하는 방법에 대해 설명하지만 IoT(사물 인터넷) 앱과 같은 사용자 지정 또는 기본 앱에 동일한 프로세스를 적용할 수 있습니다.

목표가 Azure Bot Service 채널에 연결하는 것이라면 여기 지침을 따르는 것 외에도 개발자는 Azure Bot Service 채널에 봇 연결에서 자세한 내용을 알아볼 수 있습니다.

중요

이 섹션의 지침에는 사용자 또는 개발자의 소프트웨어 개발이 필요합니다. 개발자 도구, 유틸리티 및 IDE에 대해 잘 알고 있는 IT 관리자나 개발자와 같은 숙련된 IT 전문가를 대상으로 합니다.

샘플 코드

이 문서에 사용된 코드 조각의 출처는 다음과 같습니다.

커넥터 샘플 코드

참조

이 문서의 지침은 다음 소스 자료를 참조합니다.

Copilot Studio Copilot 매개 변수 검색

빌드한 Copilot에 연결하려면 Copilot의 이름과 토큰 엔드포인트를 검색하여 식별해야 합니다.

Copilot Studio에서 Copilot 이름을 복사합니다.
탐색 메뉴에서 설정 아래의 채널을 선택합니다.
모바일 앱을 선택합니다.
토큰 엔드포인트 옆에 있는 복사를 선택합니다. Direct Line 토큰 획득 단계에는 이 엔드포인트가 필요합니다.

Direct Line 토큰 획득

Copilot과 대화를 시작하려면 Direct Line 토큰이 필요합니다. 이 토큰은 Copilot Studio 화면에 표시된 엔드포인트에 GET 요청을 하여 얻을 수 있습니다. 그런 다음 이 토큰을 Directline API에 대한 후속 호출의 헤더로 사용해야 합니다.

예:

GET <BOT TOKEN ENDPOINT>

요청이 성공하면 Direct Line 토큰, 만료 시간 및 요청된 Copilot에 대한 대화 ID가 반환됩니다. 예:

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

샘플 코드 예

다음 예에서는 커넥터 샘플 코드의 샘플을 사용하여 Copilot Studio Copilot에 대한 Direct Line 토큰을 가져옵니다.

/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
    try
    {
        return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
    }
    catch (HttpRequestException ex)
    {
        throw ex;
    }        
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
  public string Token { get; set; }
  public int Expires_in { get; set; }
  public string ConversationId { get; set; }
}

응답 개체는 앞서 본 GET 요청과 동일합니다.

{
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 3600,
  "conversationId": "abc123"
}

Direct Line을 사용하여 Copilot과 통신하기

Direct Line 토큰을 검색하면 Direct Line을 사용하여 Copilot Studio Copilot과 대화할 준비가 된 것입니다. 대화를 시작하고 메시지를 보내고 받으려면 Bot Framework Direct Line API의 지침에 따르십시오.

다음 예제는 커넥터 샘플 코드의 샘플을 사용하여 대화를 시작하고 Copilot Studio Copilot과 메시지를 주고 받습니다.

Direct Line 토큰을 사용하여 DirectLineClient 인스턴스를 초기화하고 대화를 시작합니다.

   // Use the retrieved token to create a DirectLineClient instance
   using (var directLineClient = new DirectLineClient(token))
   {
       var conversation = await directLineClient.Conversations.StartConversationAsync();
       string conversationtId = conversation.ConversationId;
   }

시작되면 각 대화는 token과 conversationtId를 조합하여 식별하고 연결할 수 있습니다. 기존 대화에 사용자 메시지를 보냅니다.

   // Use the retrieved token to create a DirectLineClient instance
   // Use the conversationId from above step
   // endConversationMessage is your predefined message indicating that user wants to quit the chat
   while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
   {
       using (var directLineClient = new DirectLineClient(token))
       {
           // Send user message using directlineClient
           // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
           await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
           {
               Type = ActivityTypes.Message,
               From = new ChannelAccount { Id = "userId", Name = "userName" },
               Text = inputMessage,
               TextFormat = "plain",
               Locale = "en-Us",
           });
       }
   }

동일한 token과 conversationId를 사용하여 Copilot의 응답을 검색합니다. 가져온 Direct Line 응답 활동에는 사용자와 Copilot의 메시지가 모두 포함됩니다. Copilot 이름으로 응답 활동을 필터링하여 Copilot의 응답 메시지만 받을 수 있습니다.

   // Use the same token to create a directLineClient
   using (var directLineClient = new DirectLineClient(token))
   {
       // To get the first response set string watermark = null
       // More information about watermark is available at
       // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0

       // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
       ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);

       // update watermark from response
       watermark = response?.Watermark;

       // response contains set of Activity from both user and bot
       // To display bot response only, filter Activity.From.Name equals to your bot name
       List<Activity> botResponses = response?.Activities?.Where(x =>
                 x.Type == ActivityTypes.Message &&
                   string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();

       // Display botResponses
   }

Direct Line 토큰 새로 고침

앱이 Copilot과 긴 대화를 가졌다면 Direct Line 토큰을 새로 고치기 위해 코드를 추가해야 할 수도 있습니다. 토큰은 만료되지만 만료되기 전에 새로 고칠 수 있습니다. 자세한 내용은 Direct Line 인증을 참조 바랍니다.

다음 예제는 커넥터 샘플 코드의 샘플을 사용하여 기존 Copilot Studio 대화에 대한 토큰을 새로 고칩니다.

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

Copilot의 대화 페이로드 구문 분석

Copilot과 대화를 시작한 후 JSON 페이로드 대화는 표준 Microsoft Bot Framework Direct Line 활동을 사용합니다. 자세한 내용은 Bot Framework Direct Line API에서 확인할 수 있습니다.

핸드오프 활동 처리

애플리케이션이 라이브 에이전트 공급자에게 핸드오프해야 하는 경우, 핸드오프 활동을 처리해야 합니다. "에이전트로 전송" 노드에 도달하면 핸드오프 활동이 전송됩니다. 핸드오프 활동의 페이로드에 대해 자세히 알아볼 수 있습니다.

환영 메시지 트리거

사용자가 대화를 시작할 때 Copilot이 인사말 시스템 토픽을 자동으로 보내려면 Type=event와 Name=startConversation으로 활동을 보낼 수 있습니다.