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

O Protocolo de Atividade é um protocolo de comunicação padrão usado em Microsoft em muitos SDKs, serviços e clientes Microsoft. O Protocolo de Atividade é usado por Microsoft 365 Copilot, Microsoft Copilot Studio e o SDK de Agentes do Microsoft 365. O Protocolo de Atividade define a estrutura de um Activity e como mensagens, eventos e interações fluem de um canal para o seu código e para todos os outros lugares entre eles. Os 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ê está 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?

Um 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 baseadas em texto. Eles podem incluir vários tipos de interação, como eventos como ingresso ou saída de usuário para clientes que dão suporte a vários usuários, indicadores de digitação, uploads de arquivos, ações de cartão e eventos personalizados que os desenvolvedores projetam.

Cada atividade inclui metadados sobre:

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

Esquema de atividade – propriedades de chave

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

Property	Description
`Id`	Normalmente gerado pelo canal se originado de um canal
`Type`	O tipo controla o significado de uma atividade, por exemplo, tipo de mensagem
`ChannelID`	Faz `ChannelID` referência ao canal do qual 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, os TurnContext desenvolvedores precisam acessar os dados dentro da atividade.

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

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Note

Os snippets de código neste artigo usam C#. A sintaxe e a estrutura de 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 uma única vez de conversa. Use-o para manter o contexto, enviar respostas apropriadas e interagir com seus usuários em seu cliente ou canal efetivamente. 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 ou métodos registrados. Esse objeto de contexto existe durante a única rodada e, em seguida, é descartado quando o turno termina.

Uma ciclo é definido como a viagem de ida e volta de uma mensagem enviada do cliente, realizando o percurso até o seu código. Seu código lida com esses dados e pode, opcionalmente, enviar uma resposta de volta para concluir o turno. Essa viagem de ida e volta pode ser dividida nas seguintes etapas:

Atividade de entrada: o usuário envia uma mensagem ou executa 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.
O turno termina e o TurnContext é descartado.

Acesse dados do TurnContext, 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 informações de chave comumente usadas incluem:

Atividade: a principal maneira de obter informações da atividade
Adaptador: o adaptador de canal que criou a atividade
TurnState: O estado da rodada

Tipos de atividade

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

Elas incluem:

Message
ConversationUpdate
Event
Invoke
Digitação

Message

Um tipo comum de atividade é o tipo mensagem de Activity. Esse Activity tipo 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 Activity notifica seu agente quando os membros ingressam ou saem de uma conversa. Nem todos os clientes dão suporte a essa notificação, mas Microsoft Teams dá.

O snippet de código a seguir 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);
            }
        }
    }
})

Events

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

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

Nome: o nome do evento ou o identificador do cliente
Valor: conteúdo de 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 é uma atividade específica que um cliente solicita a um agente para executar um comando ou operação. Não é só uma mensagem. Exemplos desses tipos de atividades são comuns no Microsoft Teams para task/fetch e task/submit. Nem todos os canais dão suporte a esses tipos de atividades.

Digitação

Um tipo de Activity é uma classificação de atividade para indicar que alguém está digitando em uma conversa. Essa atividade geralmente é vista em conversas entre humanos no cliente do Microsoft Teams, por exemplo. Não há suporte para atividades de digitação em todos os clientes. Notavelmente, Microsoft 365 Copilot não dá 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

Os agentes geralmente trabalham com anexos que os usuários (ou mesmo outros agentes) enviam. O cliente envia uma Message atividade que inclui um anexo (não é um tipo específico de atividade). Seu código precisa lidar com o recebimento da mensagem com o anexo, ler os metadados e buscar com segurança o arquivo 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 documento do 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 normalmente são de curta duração e, portanto, não suponha que as URLs permaneçam válidas por muito tempo. Essa limitação é a razão pela qual a migração para seu próprio armazenamento é importante se você precisar se referir ao conteúdo posteriormente.

Citações

É importante saber que Anexo e Citação não são do mesmo tipo de objeto. Os clientes, como Microsoft Teams, lidam com citações de suas próprias maneiras. 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 com base em seu cliente. Ele é serializado como um objeto JSON que o cliente desserializa com base em como ele é renderizado no cliente. Fundamentalmente, Anexos são mensagens e Citações podem referenciar anexos e são outro objeto enviado em Entities do payload Activity.

Considerações específicas do canal

O SDK de Agentes do Microsoft 365 é criado como um 'Hub' que os desenvolvedores usam para criar agentes que podem trabalhar com any cliente, incluindo os clientes que oferecemos suporte. Ele fornece as ferramentas para os desenvolvedores criarem seu próprio adaptador de canal usando a mesma estrutura. Essa arquitetura fornece 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.

Diferentes canais têm diferentes funcionalidades e limitações.

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

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

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

Equipes da Microsoft

Dá suporte a Cartões Adaptáveis com recursos avançados.
Dá suporte a atualizações e exclusões de mensagens.
Tem dados de canal específicos para funcionalidades do Teams, como menções e informações de reunião.
Dá suporte a atividades de invocação para módulos de tarefa.

Microsoft 365 Copilot

Focado principalmente em atividades de mensagens.
Dá suporte a citações e referências em respostas.
Requer respostas por streaming.
Suporte limitado para cartões ricos e cartões adaptáveis.

Webchat/DirectLine

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

Suporte completo para todos os tipos de atividade.
Dá suporte a dados de canal personalizados.

Canais não Microsoft

Esses canais incluem Slack, Facebook e muito mais.

Pode ter suporte limitado para determinados tipos de atividade.
A renderização de cartão pode ser diferente ou sem suporte.
Sempre verifique 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-04-29