Compreensão do Protocolo de Atividade

O Protocolo de Atividade é um protocolo padrão de comunicação utilizado em muitos SDKs, serviços e clientes da Microsoft. O Protocolo de Atividade é utilizado 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 a forma como mensagens, eventos e interações fluem de um canal para o seu código e para todos os outros pontos intermédios. Os agentes podem ligar-se a um ou mais canais para interagir com utilizadores e colaborar com outros agentes. O Protocolo de Atividade normaliza o protocolo de comunicação com qualquer cliente com o qual esteja a trabalhar, incluindo clientes Microsoft e de terceiros, para que não precise de criar uma lógica personalizada para cada canal.

O que é uma Atividade?

Uma Activity é um objeto JSON estruturado que representa qualquer interação entre um utilizador e o seu agente. As atividades não se limitam a mensagens de texto. Podem incluir vários tipos de interação, como eventos (p. ex., a entrada ou saída de um utilizador para clientes que suportam múltiplos utilizadores), indicadores de escrita, carregamentos de ficheiros, ações de cartões e eventos personalizados estruturados pelos programadores.

Cada atividade inclui metadados sobre:

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

Esquema de atividade - propriedades chave

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

Aceder aos dados da atividade

Para completar ações a partir do objeto TurnContext, os programadores precisam de aceder aos dados dentro da atividade.

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

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

O TurnContext é um objeto importante utilizado em cada turno de conversa no SDK de Agentes do Microsoft 365. Fornece acesso à atividade recebida, métodos para o envio de respostas, gestão do estado da conversa e o contexto necessário para lidar com uma única interação na conversa. Utilize-o para manter o contexto, enviar respostas adequadas e interagir com os seus utilizadores no respetivo cliente ou canal de forma eficaz. Sempre que o seu agente recebe uma nova atividade de um canal, o SDK de Agentes cria uma nova instância de TurnContext e encaminha-a para os seus processadores ou métodos registados. Este objeto de contexto existe durante um único turno e é eliminado quando o turno termina.

Um turno é definido como a viagem de ida e volta de uma mensagem enviada pelo cliente até chegar ao seu código. O seu código processa desses dados e pode, opcionalmente, enviar uma resposta para completar o turno. Essa viagem de ida e volta pode ser dividida nos seguintes passos:

1. Atividade recebida: o utilizador envia uma mensagem ou realiza uma ação que cria uma atividade.

2. O seu código recebe a atividade e o agente processa-a utilizando TurnContext.

3. O seu agente envia uma ou mais atividades de volta.

4. O turno termina e o TurnContext é eliminado.

Aceda aos dados do TurnContext, tais como:

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

Este fragmento de código mostra um exemplo de um turno completo:

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 informações chave frequentemente utilizadas 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 define o que o resto da atividade exige ou espera entre clientes, utilizadores e agentes.

Estes incluem:

• Mensagem
• ConversationUpdate
• Evento
• Invocar
• Typing

Mensagem

Um tipo comum de atividade é o tipo Mensagem de Activity. Este tipo 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 de ConversationUpdate de Activity notifica o seu agente quando membros entram ou saem de uma conversa. Nem todos os clientes suportam esta notificação, mas o Microsoft Teams sim.

O seguinte fragmento de código saúda novos membros numa 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 de Activity de Evento é um evento personalizado que os canais ou os clientes utilizam para enviar dados estruturados para o seu agente. Estes dados não estão pré-definidos na estrutura do payload Activity.

Precisa de criar um método ou processador de rotas para o tipo Event específico. Em seguida, gira a lógica pretendida com base no seguinte:

• Nome: o nome do evento ou identificador do cliente
• Valor: o payload 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 de Activity de Invocação é um tipo específico de atividade que um cliente invoca num agente para executar um comando ou uma operação. Não é apenas uma mensagem. Exemplos destes tipos de atividades são comuns no Microsoft Teams para task/fetch e task/submit. Nem todos os canais suportam estes tipos de atividades.

Typing

Um tipo de Activity de Escrita é uma classificação de atividade para indicar que alguém está a escrever numa conversação. Esta atividade é comummente observada em conversas entre pessoas na aplicação Microsoft Teams, por exemplo. As atividades de digitação não são suportadas em todos os clientes. De notar que o Microsoft 365 Copilot não suporta 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 disponibiliza vários métodos para enviar respostas ao utilizador.

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 frequentemente trabalham com anexos que os utilizadores (ou até outros agentes) submetem. O cliente envia uma atividade Message que inclui um anexo (não é um tipo específico de atividade). O seu código precisa de lidar com a receção da mensagem com o anexo, ler os metadados e obter o ficheiro de forma segura a partir do URL fornecido pelo cliente. Normalmente, move o ficheiro para o seu próprio armazenamento.

Para receber um anexo

O código seguinte 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 um pedido GET autenticado para obter o conteúdo real. Cada adaptador tem a sua própria forma de obter esses dados. Por exemplo, Teams, OneDrive, etc. Também é importante saber que esses URLs são normalmente de curta duração, por isso não se deve assumir que permanecem válidos por muito tempo. Esta limitação é a razão pela qual utilizar o seu próprio armazenamento é importante, caso precise de consultar os conteúdos mais tarde.

Citações

É importante saber que Anexo e Citação não são o mesmo tipo de objeto. Os clientes, como o Microsoft Teams, processam as citações à sua maneira. Utilizam a propriedade Entidades da Activity. Pode adicionar citações utilizando activity.Entities.Add e adicionar um novo objeto Entity que tenha a definição Citation específica de acordo com o seu cliente. Fica 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 outro objeto enviado em Entities do payload Activity.

Considerações específicas do canal

O SDK de Agentes do Microsoft 365 foi concebido como um "Hub" que os programadores utilizam para criar agentes que podem funcionar com qualquer cliente, incluindo os clientes que suportamos. Fornece as ferramentas para que os programadores possam criar o seu próprio adaptador de canal utilizando a mesma arquitetura. Esta arquitetura dá aos programadores amplitude em relação aos agentes e proporciona extensibilidade aos clientes para se ligarem a esse hub, que pode ser um ou mais clientes como o Microsoft Teams, o Slack e outros.

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

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

Os canais incluem dados específicos que não cumprem o payload Activity genérico em todos os canais. Pode aceder a estes dados a partir da propriedade TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) lançando-os para variáveis para utilização no seu código.

As secções seguintes resumem as considerações ao trabalhar com clientes comuns.

Microsoft Teams

• Suporta Cartões Adaptativos formatados com funcionalidades avançadas.
• Suporta atualizações e eliminações de mensagens.
• Contém dados específicos do canal para funcionalidades do Teams, tais como menções e informações sobre reuniões.
• Suporta atividades de invocação para módulos de tarefas.

Microsoft 365 Copilot

• Focado principalmente em atividades de mensagens.
• Suporta citações e referências nas respostas.
• Necessita de respostas transmitidas em tempo real.
• Suporte limitado para cartões avançados e cartões adaptativos.

Webchat/DirectLine

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

• Suporte total para todos os tipos de atividades.
• Suporta dados do canal personalizados.

Canais não Microsoft

Esses canais incluem Slack, Facebook e outros.

• Pode haver um suporte limitado para certos tipos de atividades.
• A composição dos cartões pode ser diferente ou não ser suportada.
• Verifique sempre a documentação específica do canal.

Passos seguintes

• Saiba mais sobre AgentApplication