Noções básicas sobre o protocolo de atividade

O protocolo Activity é o protocolo de comunicação e o protocolo padrão usado na Microsoft em muitos SDKs, serviços e clientes da Microsoft. Isso inclui o Microsoft 365 Copilot, o Microsoft Copilot Studio e o SDK do Microsoft 365 Agents. O protocolo Activity define a forma de um Activity e como as mensagens, eventos e interações fluem do canal para o seu código e para qualquer outro lugar entre eles. Os agentes podem se conectar a um ou mais canais para interagir com os usuários e trabalhar com outros agentes. O protocolo Activity padroniza o protocolo de comunicação entre qualquer cliente com o qual você esteja trabalhando, incluindo a Microsoft e clientes de terceiros, para que você não precise criar lógica personalizada por canal com o qual está trabalhando.

O que é uma Atividade?

Um Activity é um objeto JSON estruturado que representa qualquer interação entre um usuário e seu agente. As atividades não são apenas mensagens baseadas em texto, elas podem incluir vários tipos de interação, incluindo eventos como um usuário entrando ou saindo para clientes que suportam vários usuários, indicadores de digitação, uploads de arquivos, ações de cartão e eventos personalizados que os desenvolvedores projetam por conta própria.

Todas as atividades incluem metadados sobre:

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

Esquema de atividade - principais propriedades

Esta especificação define o protocolo de atividade: Protocolo de atividade - Atividade. Algumas das principais propriedades definidas no protocolo Activity são:

Propriedade	Description
`Id`	Geralmente é gerado pelo canal caso provenha de um canal.
`Type`	O tipo controla o significado de uma atividade, por exemplo, tipo de mensagem
`ChannelID`	O `ChannelID` indica o 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 de texto da mensagem
`Attachment`	Conteúdo rico como cartões, imagens de arquivos

Aceder aos dados da atividade

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

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

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Observação

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

O TurnContext é um objeto importante que é usado em cada turno de conversa no SDK de agentes do Microsoft 365. Ele fornece acesso à atividade de entrada, métodos para enviar respostas, gerenciamento de estado de conversa e o contexto necessário para lidar com um único turno de conversa. Ele é usado para manter o contexto, enviar respostas apropriadas e interagir com seus usuários em seu cliente/canal de forma eficaz. Sempre que seu agente recebe uma nova atividade de um canal, o SDK de agentes cria uma nova TurnContext instância e a passa para seus manipuladores/métodos registrados. Este objeto de contexto existe durante uma interação única e é descartado quando a interação termina.

Um turno é definido como o percurso de ida e volta de uma mensagem enviada pelo cliente até chegar ao seu código, que por sua vez processa esses dados e pode, opcionalmente, enviar uma resposta para concluir o turno. Essa viagem de ida e volta pode ser dividida em:

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

Aceda a dados do TurnContext, tais como:

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

Este trecho de código mostra um exemplo de uma volta 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, as TurnContext 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 para o turno

Tipos de atividade

O tipo de atividade é importante, pois define o que é necessário ou esperado no restante da atividade entre clientes, usuários e agentes.

Message

Um tipo comum de atividade é o tipo de mensagemActivity, que pode incluir texto, anexos e ações sugeridas para exemplificar alguns dos usos comuns deste tipo.

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

Atualização da Conversa

O tipo de ConversationUpdate de Activity notifica o seu agente quando membros entram ou saem de uma conversa. Nem todos os clientes suportam isso, um cliente notável que faz é o Microsoft Teams.

O trecho de código a seguir saúda 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.Reciepient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Events

O tipo de Evento de Activity corresponde a eventos personalizados que permitem que canais ou clientes enviem dados estruturados para o seu agente, que não estão predefinidos na estrutura payload de Activity.

Você precisaria criar um manipulador de método/rota para o tipo específico Event e, em seguida, gerenciar a lógica desejada com base na:

Nome - O nome ou identificador do evento do cliente Valor - Dados 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)
}

Invoke

Um tipo Invoke de Activity é um tipo específico de atividade em que um cliente invoca um agente para executar um comando ou operação, e não apenas enviar uma mensagem. Exemplos desses tipos de atividades são comuns no Microsoft Teams para task/fetch e task/submit. Nem todos os canais suportam este tipo de atividades.

Digitação

Um tipo de Escrita de Activity é uma classificação de atividade para indicar que alguém está a escrever numa conversa. Isso é comumente visto entre conversas entre humanos no cliente Microsoft Teams, por exemplo. As atividades de digitação não são suportadas em todos os clientes e, notavelmente, 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' fornece vários métodos para enviar respostas de volta 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

É comum que os agentes trabalhem com anexos que foram enviados por usuários (ou até mesmo por outros agentes). O cliente envia uma Message atividade que inclui um anexo (não é um tipo específico de atividade) e seu código precisa lidar com o recebimento da mensagem com o anexo, ler os metadados e buscar o arquivo com segurança da URL que o cliente forneceu. É recomendado, depois, mover o ficheiro para o seu próprio armazenamento.

Para receber um anexo

O código a seguir mostra como receber e anexar

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 documento no anexo, o cliente envia uma solicitação autenticada GET para recuperar o conteúdo real - cada adaptador tem sua própria maneira de obter esses dados, por exemplo, Teams, OneDrive e assim por diante. Também é importante saber que essas urls são normalmente de curta duração e, portanto, não assuma que elas permanecerão lá, e é por isso que mudar para seu próprio armazenamento é importante se você precisar se referir a isso mais tarde.

Citações

É importante saber que Anexo e Citação não são o mesmo tipo de objeto. As citações são processadas por Clientes, como o Microsoft Teams, de formas específicas, e utilizam a propriedade Entidades da Activity e podem ser adicionadas através de activity.Entities.Add, adicionando um novo objeto Entity que contém a definição Citation específica com base no seu cliente. Esse objeto é serializado como um objeto JSON, e o cliente, depois, anula a serialização com base na forma como é composto no cliente. Fundamentalmente, os Anexos são mensagens, e as Citações podem fazer referência a anexos e são um outro objeto enviado em Entities do payload Activity.

Considerações específicas do canal

O SDK do Microsoft 365 Agents é construído como um 'Hub' que permite que os desenvolvedores criem agentes que podem trabalhar com qualquer cliente, incluindo os clientes aos quais damos suporte e fornecem as ferramentas para que os desenvolvedores criem seu próprio adaptador de canal usando a mesma estrutura. Isso dá aos desenvolvedores amplitude quando se trata de agentes e fornece extensibilidade aos clientes para se conectarem a esse hub, que pode ser um ou mais clientes como Microsoft Teams, Slack e muito mais.

Canais diferentes têm diferentes capacidades e limitações, e a seguir está um resumo das considerações ao trabalhar com clientes comuns.

Pode verificar o canal de onde recebeu a atividade inspecionando a propriedade channelId na Activity.

Os canais incluem dados específicos que não estão em conformidade com o payload genérico Activity em todos os canais, e é possível aceder a isto a partir de TurnContext.Activity.ChannelData, convertendo-os especificamente em variáveis para utilização no seu código.

Microsoft Teams

Suporta Cartões Adaptativos formatados com funcionalidades avançadas
Suporta atualizações e exclusões de mensagens
Contém dados de canal específicos para funcionalidades do Teams (menções, informações de reuniões, entre outras)
Suporta atividades de invocação para módulos de tarefas

Microsoft 365 Copilot

Focado principalmente em atividades de mensagem
Suporta citações e referências nas respostas
Requer respostas de streaming
Suporte limitado para cartões ricos/cartões adaptáveis

WebChat/DirectLine

Web Chat é um protocolo HTTP usado para agentes falarem por HTTPS

Suporte completo para todos os tipos de atividade
Suporta dados de canal personalizados

Canais de terceiros

Estes incluem Slack, Facebook e muito mais.

Pode ter suporte limitado para determinados tipos de atividade
A renderização do cartão pode ser diferente ou não ser suportada
Verifique sempre a documentação específica do canal

Feedback

Esta página foi útil?

Last updated on 2025-11-19