활동 프로토콜 이해

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

활동이란?

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

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

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

활동 스키마 - 키 속성

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

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

활동 데이터 액세스

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

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

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

비고

이 문서의 코드 조각은 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: 턴의 상태입니다.

활동 유형

활동의 유형은 나머지 활동이 클라이언트, 사용자 및 에이전트 간에 필요하거나 기대하는 것을 정의합니다.

여기에는 다음이 포함됩니다.

메시지
대화 업데이트
Event
호출
Typing

메시지

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

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.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

이벤트

이벤트 유형 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)
});

호출

호출 유형 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 같은 클라이언트는 고유한 방식으로 인용을 처리합니다. 의 Entities 속성을Activity사용합니다. 클라이언트에 따라 activity.Entities.Add를 사용하여 인용을 추가하고, 특정 Entity 정의가 포함된 새로운 Citation 개체를 추가할 수 있습니다. 클라이언트가 렌더링하는 방식에 따라 클라이언트에서 역직렬화하는 JSON 개체로 직렬화됩니다. 기본적으로 첨부 파일은 메시지이며 인용은 첨부 파일을 참조할 수 있으며 Activity 페이로드의 Entities에서 전송된 다른 개체입니다.

채널별 고려 사항

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

채널에 따라 기능과 제한 사항이 다릅니다.

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

채널에는 모든 채널에서 일반 Activity 페이로드를 준수하지 않는 특정 데이터가 포함됩니다. TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) 속성에서 이 데이터를 코드에서 사용할 변수로 캐스팅하여 액세스할 수 있습니다.

다음 섹션에서는 일반 클라이언트로 작업할 때의 고려 사항을 요약합니다.

Microsoft 팀

적응형 카드를 고급 기능과 함께 풍부하게 지원합니다.
메시지 업데이트 및 삭제를 지원합니다.
멘션 및 모임 정보와 같은 Teams 기능에 대한 특정 채널 데이터가 있습니다.
작업 모듈에 대한 호출 작업을 지원합니다.

Microsoft 365 Copilot

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

웹 채팅/DirectLine

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

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

비 Microsoft 채널

이러한 채널에는 Slack, Facebook 등이 포함됩니다.

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

다음 단계

AgentApplication에 대해 알아보기

피드백

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

Last updated on 2026-04-29