활동 프로토콜 이해

활동 프로토콜은 많은 Microsoft SDK, 서비스 및 클라이언트에서 Microsoft 전체에서 사용되는 통신 프로토콜 및 표준 프로토콜입니다. 여기에는 Microsoft 365 Copilot, Microsoft Copilot Studio 및 Microsoft 365 에이전트 SDK가 포함됩니다. 활동 프로토콜은 메시지, 이벤트 및 상호 작용이 Activity 채널에서 코드로, 그리고 그 사이의 다른 모든 곳에서 흐르는 방식과 모양을 정의합니다. 에이전트는 하나 이상의 채널에 연결하여 사용자와 상호 작용하고 다른 에이전트와 작업할 수 있습니다. 작업 프로토콜은 Microsoft 및 타사 클라이언트를 포함하여 작업 중인 모든 클라이언트 간의 통신 프로토콜을 표준화하므로 작업 중인 채널당 사용자 지정 논리를 만들 필요가 없습니다.

활동이란?

Activity 사용자와 귀하의 에이전트 간의 모든 상호 작용을 나타내는 구조화된 JSON 객체입니다. 활동은 텍스트 기반 메시지뿐만 아니라 여러 사용자를 지원하는 클라이언트에 대한 사용자 가입 또는 종료, 입력 표시기, 파일 업로드, 카드 작업 및 개발자가 직접 디자인하는 사용자 지정 이벤트와 같은 다양한 유형의 상호 작용을 포함할 수 있습니다.

모든 활동에는 다음에 대한 메타데이터가 포함됩니다.

누가 보냈는지 (출처)
수신해야 하는 사람(수신자)
대화 컨텍스트
기원이 된 채널
상호 작용의 유형
페이로드 데이터

활동 스키마 - 키 속성

이 사양은 활동 프로토콜: 활동 프로토콜 - 활동을 정의합니다. 작업 프로토콜에 정의된 몇 가지 주요 속성은 다음과 같습니다.

재산	Description
`Id`	일반적으로 채널에서 발생하는 경우 채널에서 생성됩니다.
`Type`	형식은 활동의 의미를 제어합니다(예: 메시지 형식).
`ChannelID`	활동이 `ChannelID` 시작된 채널을 참조합니다. 예: `msteams`.
`From`	활동의 보낸 사람(사용자 또는 에이전트일 수 있습니다).
`Recipient`	활동의 의도된 수신자
`Text`	메시지의 텍스트 내용
`Attachment`	카드, 파일 이미지와 같은 풍부한 콘텐츠

활동 데이터 액세스

개발자가 TurnContext 개체에서 작업을 완료하려면 활동 내의 데이터에 액세스해야 합니다.

Microsoft 365 에이전트 SDK의 각 언어 버전에서 TurnContext 클래스를 찾을 수 있습니다.

.NET: 턴컨텍스트
파이썬: 턴컨텍스트
자바스크립트: 턴컨텍스트

비고

이 문서의 코드 조각은 C#을 사용합니다. JavaScript 및 Python 버전의 구문 및 API 구조는 비슷합니다.

이 TurnContext 개체는 Microsoft 365 에이전트 SDK의 모든 대화 턴에서 사용되는 중요한 개체입니다. 들어오는 활동, 응답을 보내는 방법, 대화 상태 관리 및 단일 대화 턴을 처리하는 데 필요한 컨텍스트에 대한 액세스를 제공합니다. 컨텍스트를 유지하고, 적절한 응답을 보내고, 클라이언트/채널에서 사용자와 효과적으로 상호 작용하는 데 사용됩니다. 에이전트가 채널에서 새 활동을 받을 때마다 에이전트 SDK는 새 TurnContext 인스턴스를 만들고 등록된 처리기/메서드에 전달합니다. 이 컨텍스트 개체는 단일 턴 중에 존재하며 턴이 끝나면 삭제됩니다.

순서는 클라이언트에서 보낸 메시지의 왕복으로 정의되고 코드로 이동하며 코드는 해당 데이터를 처리하고 코드는 필요에 따라 응답을 다시 보내 턴을 완료할 수 있습니다. 해당 왕복은 다음으로 나눌 수 있습니다.

들어오는 작업: 사용자가 메시지를 보내거나 활동을 만드는 작업을 수행합니다.
코드는 활동을 수신하고 에이전트는 TurnContext을 사용하여 처리합니다.
에이전트가 하나 이상의 활동을 다시 보냅니다.
턴이 종료되고 TurnContext 삭제됩니다.

데이터는 TurnContext에서 액세스합니다, 예를 들어:

var messageText = turnContext.Activity.Text
var channelID = turnContext.Activity.ChannelId

이 코드 조각은 전체 턴의 예를 보여줍니다.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

클래스 내에서 TurnContext 일반적으로 사용되는 키 정보에는 다음이 포함됩니다.

활동: 활동에서 정보를 가져오는 주요 방법
어댑터: 활동을 만든 채널 어댑터
TurnState: 턴의 상태입니다.

활동 유형

활동의 유형은 클라이언트, 사용자 및 에이전트 간의 나머지 활동에서 필요하거나 예상되는 항목을 정의하기 때문에 중요합니다.

Message

작업의 일반적인 유형은 메시지 형식입니다. 이 형식에는 텍스트, 첨부 파일, 일부 일반적인 용도로 제안된 작업 등이 포함될 수 있습니다.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

대화 업데이트

ConversationUpdate 형식 Activity 은 구성원이 대화에 참가하거나 대화에서 나갈 때 에이전트에 알깁니다. 모든 클라이언트가 이를 지원하는 것은 아니며, 주목할 만한 클라이언트는 Microsoft Teams입니다.

다음 코드 조각은 대화에서 새 멤버를 맞이합니다.

agent.OnActivity(ActivityTypes.ConversationUpdate, async (turnContext turnState, cancellationToken) =>
{
    var membersAdded = turnContext.Activity.MembersAdded
    if (membersAdded != null)
    {
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Reciepient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Events

이벤트 유형 Activity 은 채널 또는 클라이언트가 페이로드 구조에 Activity 미리 정의되지 않은 에이전트에 구조화된 데이터를 보낼 수 있도록 하는 사용자 지정 이벤트입니다.

특정 Event 형식에 대한 메서드/경로 처리기를 만든 다음 다음을 기반으로 원하는 논리를 관리해야 합니다.

이름 - 클라이언트 값 의 이벤트 이름 또는 식별자 - 일반적으로 JSON 개체인 이벤트 페이로드

agent.OnActivity(ActivityTypes.Event, async (turnContext turnState, cancellationToken) =>)
{
    var eventName = turnContext.Activity.Name
    var eventValue = turnContext.Activity.Value

    // custom event (E.g. a switch on eventName)
}

Invoke

호출 유형 Activity 은 클라이언트가 메시지뿐만 아니라 명령 또는 작업을 수행하기 위해 에이전트로 호출하는 특정 유형의 활동입니다. 이러한 유형의 활동 예는 Microsoft Teams에서 task/fetch 및 task/submit에서 일반적입니다. 모든 채널이 이러한 유형의 활동을 지원하는 것은 아닙니다.

Typing

입력 유형 Activity 은 대화에서 다른 사람이 입력하고 있음을 나타내는 활동의 분류입니다. 예를 들어 Microsoft Teams 클라이언트에서 인간과 사람의 대화 간에 일반적으로 표시됩니다. 입력 작업은 모든 클라이언트에서 지원되지 않으며, 특히 Microsoft 365 Copilot는 입력 작업을 지원하지 않습니다.

await turnContext.SendActivityAsync(new Activity { Type = ActivityTypes.Typing }, cancellationToken); 
await Task.Delay(2000);
await turnContext.SendActivityAsync(MessageFactory.Text("Here is your answer..."), cancellationToken)

활동 만들기 및 보내기

응답을 보내기 위해 'TurnContext'는 사용자에게 응답을 다시 보내기 위한 여러 메서드 를 제공합니다.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken))
{
    await turnContext.SendActivityAsync("hello!", cancellationToken: CancellationToken) // uses string directly
    await turnContext.SendActivityAsync(MessageFactory.Text("Hello"), cancellationToken) // uses Message Factory
    await turnContext.SendActivitiesAsync(activities, cancellationToken) // send multiple activities in an Activity array
}

첨부 파일로 작업

에이전트는 사용자(또는 다른 에이전트)가 제출한 첨부 파일을 사용하는 것이 일반적입니다. 클라이언트는 첨부 파일이 포함된 작업(특정 유형의 활동이 아님)을 보내고 Message , 코드는 첨부 파일로 메시지 수신을 처리하고, 메타데이터를 읽고, 클라이언트가 제공한 URL에서 파일을 안전하게 가져와야 합니다. 그런 다음 파일을 사용자 고유의 스토리지로 이동하는 것이 일반적입니다.

첨부 파일을 받으려면

다음 코드는 수신 및 첨부 파일을 받는 방법을 보여줍니다.

agent.OnActivity(ActivityTypes.Message, async(turnContext, turnState, cancellationToken)) =>
{
    var activity = turnContext.Activity;
    if (activity.Attachments != null && activity.Attachments.Count >0)
    {
        foreach (var attachment in activity.Attachments)
        {
            // get metadata as required e.g. attachment.ContextType or attachment.ContentUrl
            // use the URL to securely download the attachment and complete your business logic
        }
    }
}

일반적으로 클라이언트는 첨부 파일에서 문서를 수신하기 위해 실제 콘텐츠를 검색하기 위해 인증된 GET 요청을 보냅니다. 각 어댑터는 Teams, OneDrive 등과 같은 고유한 방식으로 해당 데이터를 가져올 수 있습니다. 또한 이러한 URL은 일반적으로 수명이 짧으므로 해당 URL이 유지된다고 가정하지 않는 것이 중요합니다. 따라서 나중에 이를 참조해야 하는 경우 사용자 고유의 스토리지로 이동하는 것이 중요합니다.

인용

첨부 파일 및 인용이 동일한 개체 형식이 아니라는 것을 알아야 합니다. 클라이언트(예: Microsoft Teams)는 인용을 고유한 방식으로 처리하며, 엔터티 속성을 사용합니다. 클라이언트에 따라 특정 Activity 정의가 있는 새로운 activity.Entities.Add 객체를 Entity와 함께 추가할 수 있습니다. 클라이언트가 렌더링하는 방식에 따라 클라이언트에서 역직렬화하는 JSON 개체로 직렬화됩니다. 기본적으로 첨부 파일은 메시지이며, 인용은 첨부 파일을 참조할 수 있는 또 다른 개체로서 페이로드의 EntitiesActivity에서 전송됩니다.

채널별 고려 사항

Microsoft 365 에이전트 SDK는 개발자가 지원하는 클라이언트를 포함하여 모든 클라이언트에서 작업할 수 있는 에이전트를 만들고 개발자가 동일한 프레임워크를 사용하여 자체 채널 어댑터를 빌드할 수 있는 도구를 제공할 수 있는 '허브'로 빌드됩니다. 이를 통해 개발자는 에이전트와 관련하여 폭넓은 기능을 제공하고, 클라이언트가 해당 허브에 연결할 수 있는 확장성을 제공하며, Microsoft Teams, Slack 등과 같은 하나 이상의 클라이언트가 될 수 있습니다.

채널에 따라 기능과 제한 사항이 다르며, 다음은 공통 클라이언트로 작업할 때 고려해야 할 사항을 요약한 것입니다.

channelId에서 Activity 속성을 확인하여 활동을 받은 채널을 확인할 수 있습니다.

채널에는 모든 채널에서 일반 Activity 페이로드를 준수하지 않는 특정 데이터가 포함되며 TurnContext에서 액세스할 수 있습니다.Activity.ChannelData 및 특히 코드에서 사용할 변수로 캐스팅합니다.

Microsoft 팀

고급 기능으로 풍부한 적응형 카드 지원
메시지 업데이트 및 삭제 지원
Teams 기능에 대한 특정 채널 데이터(멘션, 모임 정보 등) 포함
작업 모듈에 대한 작업 호출 지원

Microsoft 365 Copilot

주로 메시지 활동에 초점을 맞췄습니다.
응답에서 인용 및 참조 지원
스트리밍 응답 필요
리치 카드/적응형 카드에 대한 제한된 지원

WebChat/DirectLine

웹 채팅은 에이전트가 HTTPS를 통해 통신하는 데 사용되는 HTTP 프로토콜입니다.

모든 활동 유형에 대한 전체 지원
사용자 지정 채널 데이터 지원

타사 채널

여기에는 Slack, Facebook 등이 포함된다.

특정 활동 유형에 대한 지원이 제한될 수 있습니다.
카드 렌더링이 다르거나 지원되지 않을 수 있습니다.
항상 특정 채널 설명서 확인

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-10-21