Noções básicas sobre o Protocolo de Atividade

Protocolo de Atividade é um protocolo de comunicação padrão usado na Microsoft em muitos SDKs, serviços e clientes da Microsoft. O Protocolo de Atividade é usado pelo Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams e pelo SDK de Agentes do Microsoft 365. O Protocolo de Atividade define a estrutura de uma Activity e como mensagens, eventos e interações fluem de um canal para o seu código e em todos os demais lugares intermediários. Agentes podem se conectar a um ou mais canais para interagir com usuários e trabalhar com outros agentes. O Protocolo de Atividade padroniza o protocolo de comunicação com qualquer cliente com o qual você esteja trabalhando, incluindo clientes Microsoft e não Microsoft, para que você não precise criar lógica personalizada para cada canal.

O que é uma Atividade?

Uma Activity é um objeto JSON estruturado que representa qualquer interação entre um usuário e seu agente. As atividades não se limitam a mensagens de texto. Elas podem incluir vários tipos de interação, como eventos de entrada ou saída de usuários para clientes que oferecem suporte a vários usuários, indicadores de digitação, upload de arquivos, ações de cartões e eventos personalizados criados por desenvolvedores.

Cada atividade inclui metadados sobre:

Quem a enviou (remetente)
Quem deve recebê-la (destinatário)
O contexto da conversa
O canal de onde ela se originou
O tipo de interação
Os dados do conteúdo

Esquema da Atividade – propriedades principais

Esta especificação define o Protocolo de Atividade: Protocolo de Atividade – Atividade. Algumas das principais propriedades definidas no Protocolo de Atividade são:

Propriedade	descrição
`Id`	Normalmente gerado pelo canal em caso de origem em um canal
`Type`	O tipo controla o significado de uma atividade, por exemplo, tipo de mensagem
`ChannelID`	A `ChannelID` faz referência ao canal de onde a atividade se originou. Por exemplo: `msteams`.
`From`	O remetente da atividade (que pode ser um usuário ou agente)
`Recipient`	O destinatário pretendido da atividade
`Text`	O conteúdo do texto da mensagem
`Attachment`	Conteúdo avançado como cartões, imagens de arquivos

Acessar dados de atividade

Para concluir ações do objeto TurnContext, os desenvolvedores precisam acessar os dados dentro da atividade.

Você pode encontrar uma classe TurnContext em cada versão de linguagem do SDK de Agentes do Microsoft 365:

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Observação

Os trechos de código neste artigo usam C#. A sintaxe e a estrutura da API das versões JavaScript e Python são semelhantes.

TurnContext é um objeto importante que é usado em todas as conversas no SDK de Agentes do Microsoft 365. Ele fornece acesso à atividade recebida, métodos para enviar respostas, gerenciamento do estado da conversa e o contexto necessário para lidar com uma única rodada de conversa. Use-o para manter o contexto, enviar respostas apropriadas e interagir com seus usuários em seu cliente ou canal com eficiência. Sempre que seu agente recebe uma nova atividade de um canal, o SDK de Agentes cria uma instância de TurnContext e a repassa aos seus manipuladores ou métodos registrados. Este objeto de contexto permanece ativo durante uma única rodada e é descartado ao final da rodada.

Um turno é definido como a viagem de ida e volta de uma mensagem enviada do cliente, realizando a jornada até o seu código. Seu código lida com esses dados e pode, opcionalmente, enviar uma resposta para concluir a rodada. Esse ciclo pode ser dividido nas etapas a seguir:

Atividade recebida: o usuário envia uma mensagem ou realiza uma ação que cria uma atividade.
Seu código recebe a atividade e o agente a processa usando TurnContext.
O seu agente envia de volta uma ou mais atividades.
A rodada termina e o TurnContext é descartado.

Acesse dados de TurnContext, como:

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

Este trecho de código mostra um exemplo de uma rodada completa:

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);
});

Dentro da classe TurnContext, as principais informações comumente usadas incluem:

Atividade: a principal forma de obter informações da atividade
Adaptador: o adaptador de canal que criou a atividade
TurnState: o estado do turno

Tipos de Atividade

O tipo de atividade define o que o restante da atividade exige ou espera entre clientes, usuários e agentes.

Elas incluem:

Mensagem
ConversationUpdate
Evento
Invocar
Digitação

Mensagem

Um tipo comum de atividade é o tipo Mensagem de Activity. Esse tipo de Activity pode incluir texto, anexos e ações sugeridas.

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

O tipo ConversationUpdate de Activity notifica seu agente quando membros ingressam ou deixam uma conversa. Nem todos os clientes oferecem suporte a essa notificação, mas o Microsoft Teams oferece.

O seguinte trecho de código cumprimenta novos membros em uma conversa:

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);
            }
        }
    }
})

Eventos

O tipo Evento de Activity é um evento personalizado que canais ou clientes usam para enviar dados estruturados ao seu agente. Esses dados não são predefinidos na estrutura de conteúdo da Activity.

Você precisa criar um método ou um manipulador de rotas para o tipo Event específico. Depois, gerencie a lógica desejada com base no:

Nome: o nome do evento ou identificador fornecido pelo cliente
Valor: conteúdo do evento que normalmente é um objeto 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)
});

Invocar

Um tipo Invocar de Activity é um tipo específico de atividade em que um cliente chama um agente para realizar um comando ou operação. Não é apenas uma mensagem. Exemplos desses tipos de atividades são comuns no Microsoft Teams para task/fetch e task/submit. Nem todos os canais oferecem suporte a esses tipos de atividades.

Digitação

Um tipo de Digitação é tipo de Activity classificação de atividade para indicar que alguém está digitando em uma conversa. Essa atividade é comumente vista em conversas entre pessoas no cliente Microsoft Teams, por exemplo. Não há suporte a atividades de digitação em todos os clientes. Vale ressaltar que o Microsoft 365 Copilot não oferece suporte a atividades de digitação.

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

Criar e enviar atividades

Para enviar respostas, o TurnContext oferece vários métodos para enviar respostas ao usuário.

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
}

Trabalhar com anexos

Agentes frequentemente trabalham com anexos que usuários (ou até outros agentes) enviam. O cliente envia uma atividade de Message que inclui um anexo (não é um tipo específico de atividade). Seu código deve tratar o recebimento da mensagem com o anexo, ler os metadados e obter o arquivo com segurança a partir da URL fornecida pelo cliente. Normalmente, você move o arquivo para seu próprio armazenamento.

Para receber um anexo

O código a seguir mostra como receber um anexo.

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
        };
    }
}

Normalmente, para receber o arquivo do anexo, o cliente envia uma requisição autenticada GET para recuperar o conteúdo real. Cada adaptador tem seu próprio método para obter esses dados. Por exemplo, Teams, OneDrive etc. Também é importante saber que essas URLs geralmente têm vida curta, portanto, não presuma que elas permanecem válidas por muito tempo. Essa limitação é o motivo pelo qual mover para seu próprio armazenamento é importante caso você precise consultar o conteúdo posteriormente.

Citações

É importante saber que Anexo e Citação não são o mesmo tipo de objeto. Clientes, como o Microsoft Teams, tratam citações de formas distintas. Eles utilizam a propriedade Entities do Activity. Você pode adicionar citações com activity.Entities.Add e adicionar um novo objeto Entity que tenha a definição específica Citation baseada no seu cliente. O objeto é serializado como um objeto JSON que o cliente então desserializa de acordo com a forma como ele é renderizado no cliente. Basicamente, anexos são mensagens, e Citações podem fazer referência a anexos, sendo outro objeto enviado em Entities do conteúdo de Activity.

Configurações específicas de canal

O SDK de Agentes do Microsoft 365 foi criado como um 'Hub' para que os desenvolvedores criem agentes que possam trabalhar com qualquer cliente, incluindo os clientes aos quais oferecemos suporte. Ele fornece as ferramentas para que desenvolvedores criem seu próprio adaptador de canal usando a mesma estrutura. Essa arquitetura oferece aos desenvolvedores maior abrangência em relação aos agentes e proporciona extensibilidade para que os clientes se conectem a esse hub, que pode incluir um ou mais clientes, como Microsoft Teams, Slack e outros.

Canais diferentes têm capacidades e limitações distintas.

Você pode verificar o canal do qual recebeu a atividade inspecionando a propriedade channelId na Activity.

Os canais incluem dados específicos que não estão em conformidade com o conteúdo genérico de Activity em todos os canais. Você pode acessar esses dados a partir da propriedade TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) projetando-os para variáveis para uso no seu código.

As seções a seguir resumem as considerações ao trabalhar com clientes comuns.

Microsoft Teams

Oferece suporte a Cartões Adaptáveis sofisticados com recursos avançados.
Oferece suporte a atualizações e exclusões de mensagens.
Tem dados de canal específicos para recursos do Teams, como menções e informações de reuniões.
Oferece suporte a atividades de invocar para módulos de tarefas.

Microsoft 365 Copilot

Focado principalmente em atividades de mensagem.
Oferece suporte a citações e referências nas respostas.
Exige respostas de streaming.
Suporte limitado para cartões sofisticados e cartões adaptáveis.

Webchat/DirectLine

Webchat é um protocolo HTTP que os agentes podem usar para se comunicar via HTTPS.

Suporte total a todos os tipos de atividades.
Oferece suporte a dados de canal personalizados.

Canais que não são da Microsoft

Esses canais incluem Slack, Facebook, entre outros.

Pode haver suporte limitado a certos tipos de atividade.
A renderização de cartões pode ser diferente ou não ter suporte.
Consulte sempre a documentação específica do canal.

Próximas etapas

Saiba mais sobre AgentApplication

Comentários

Esta página foi útil?

Last updated on 2026-07-29