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

O protocolo Activity é o protocolo de comunicação e o protocolo padrão usados 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 de atividade define a forma de um Activity e como mensagens, eventos e interações fluem do canal para o seu código e em todos os demais lugares intermediários. Os agentes podem se conectar a um ou mais canais para interagir com usuários e trabalhar com outros agentes. O protocolo atividade padroniza o protocolo de comunicação entre qualquer cliente com o qual você está 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, como eventos, por exemplo, a entrada ou saída de usuários em clientes que suportam múltiplos usuários, indicadores de digitação, uploads de arquivos, ações de cartões e eventos personalizados que os desenvolvedores criam.

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

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

Dados da atividade de acesso

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 SDK do Microsoft 365 Agents:

• .NET: TurnContext
• Python: TurnContext
• JavaScript: TurnContext

O TurnContext é um objeto importante usado em cada turno de conversa no SDK do Microsoft 365 Agents. 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. Ele é usado para manter o contexto, enviar respostas apropriadas e interagir com os usuários em seu cliente/canal com eficiência. Toda vez 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. Esse objeto de contexto existe durante uma interação única e é descartado depois que a interação termina.

Um turno é definido como a viagem de ida e volta de uma mensagem enviada pelo cliente até seu código; o código manipula esses dados e pode enviar uma resposta de volta para concluir o turno. Essa viagem de ida e volta pode ser dividida em:

1. Atividade de entrada: o usuário envia uma mensagem ou executa uma ação que cria uma atividade.
2. Seu código recebe a atividade e o agente a processa usando TurnContext.
3. O seu agente envia de volta uma ou mais atividades.
4. 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 do 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 mensagem , Activityque pode incluir texto, anexos e ações sugeridas para nomear alguns usos comuns para esse 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);
});

ConversationUpdate

O tipo Activity notifica seu agente quando os membros ingressam ou saem de uma conversa. Nem todos os clientes dão suporte a isso, um cliente notável que faz isso é o Microsoft Teams.

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

Eventos

O tipo de evento de Activity são eventos personalizados que permitem que canais ou clientes enviem dados estruturados para seu agente, o que não é predefinido na Activity estrutura de conteúdo.

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 no:

Nome – O nome do evento ou o identificador do valor do cliente – 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)
}

Invoke

Um tipo Invoke é um tipo Activity específico de atividade em que um cliente está solicitando a um agente a realização de um comando ou operação, e não apenas enviando 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 esse tipo de atividade.

Digitação

Um tipo de Typing é tipo de Activity classificação de atividade para indicar que alguém está digitando em uma conversa. Isso geralmente é visto em conversas entre humanos no cliente Microsoft Teams, por exemplo. Não há suporte para atividades de digitação em todos os clientes e, notavelmente, o 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

É comum que os agentes trabalhem com anexos que foram enviados por usuários (ou até mesmo 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 com segurança o arquivo da URL fornecida pelo cliente. Em seguida, seria comum mover o arquivo para 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 normalmente são de curta duração e, portanto, não suponha 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 do mesmo tipo de objeto. Citações são tratadas por clientes, como o Microsoft Teams, de maneiras próprias, e usam a propriedade Entities do Activity e podem ser adicionadas com activity.Entities.Add, além de um novo objeto Entity que contenha uma definição específica Citation com base no cliente. Ele seria 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, sendo outro objeto enviado no Entities do Activity conteúdo.

Considerações específicas do canal

O SDK do Microsoft 365 Agents é criado como um "Hub" que permite aos desenvolvedores criar agentes que possam trabalhar com qualquer cliente, incluindo os clientes que oferecemos suporte e fornecemos as ferramentas para os desenvolvedores criarem seu próprio adaptador de canal usando a mesma estrutura. Isso proporciona 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, e o seguinte é um resumo das considerações ao trabalhar com clientes comuns.

Você pode verificar de qual canal recebeu a atividade inspecionando a propriedade channelId no 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 isso pode ser acessado por meio de TurnContext.Activity.ChannelData, convertendo-o especificamente em variáveis para utilização no seu código.

Equipes da Microsoft

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

Microsoft 365 Copilot

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

WebChat/DirectLine

O Web Chat é um protocolo HTTP usado para os agentes falarem sobre HTTPS

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

Canais de terceiros

Isso inclui 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