Descripción del protocolo de actividad

El protocolo de actividad es el protocolo de comunicación y el protocolo estándar que se usan en Microsoft en muchos SDK, servicios y clientes de Microsoft. Esto incluye Microsoft 365 Copilot, Microsoft Copilot Studio y el SDK de agentes de Microsoft 365. El protocolo de Activity define la estructura de un Activity y cómo fluyen los mensajes, eventos e interacciones desde el canal, hasta tu código y a cualquier otro lugar intermedio. Los agentes pueden conectarse a uno o varios canales para interactuar con los usuarios y trabajar con otros agentes. El protocolo de actividad normaliza el protocolo de comunicación entre cualquier cliente con el que esté trabajando, incluidos los clientes de Microsoft y de terceros, por lo que no tiene que crear lógica personalizada por canal con el que esté trabajando.

¿Qué es una actividad?

es Activity un objeto JSON estructurado que representa cualquier interacción entre un usuario y tu agente. Las actividades no son solo mensajes basados en texto, pueden incluir varios tipos de interacción, incluidos eventos como la unión de usuarios o la salida de clientes que admiten varios usuarios, indicadores de escritura, cargas de archivos, acciones de tarjeta y eventos personalizados que los desarrolladores diseñan por sí mismos.

Cada actividad incluye metadatos sobre:

• Quién lo envió (desde)
• Quién debe recibirlo (destinatario)
• Contexto de conversación
• Canal del que se originó
• Tipo de interacción
• Datos de carga

Esquema de actividad: propiedades clave

Esta especificación define el protocolo de actividad: Protocolo de actividad: Actividad. Algunas de las propiedades clave definidas en el protocolo de actividad son:

Propiedad	Description
Id	Normalmente generado por el canal si se origina desde un canal
Type	El tipo controla el significado de una actividad, por ejemplo, el tipo de mensaje.
ChannelID	hace ChannelID referencia al canal desde el que se originó la actividad. Por ejemplo: msteams.
From	Remitente de la actividad (que puede ser un usuario o agente)
Recipient	Destinatario previsto de la actividad
Text	El contenido del texto del mensaje
Attachment	Contenido enriquecido como tarjetas, imágenes de archivos

Datos de actividad de acceso

Los desarrolladores deben acceder a los datos de la actividad para completar acciones desde el TurnContext objeto .

Puede encontrar una TurnContext clase en cada versión de idioma del SDK de agentes de Microsoft 365:

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

Nota:

Los fragmentos de código de este artículo usan C#. La sintaxis y la estructura de API de las versiones de JavaScript y Python son similares.

TurnContext es un objeto importante que se utiliza en cada turno de conversación dentro del SDK de agentes de Microsoft 365. Proporciona acceso a la actividad entrante, métodos para enviar respuestas, administración de estado de conversación y el contexto necesario para controlar un solo turno de conversación. Se usa para mantener el contexto, enviar respuestas adecuadas e interactuar con los usuarios en su cliente o canal de forma eficaz. Cada vez que tu agente recibe una nueva actividad de un canal, el SDK del agente crea una nueva TurnContext instancia y la pasa a tus manejadores o métodos registrados. Este objeto de contexto existe durante el turno único y, a continuación, se elimina de una vez que finaliza el turno.

Un turno se define como el viaje de ida y vuelta de un mensaje enviado desde el cliente hasta su código; el código procesa esos datos y puede enviar opcionalmente una respuesta para completar el turno. Ese recorrido de ida y vuelta se puede dividir en:

1. Actividad entrante: el usuario envía un mensaje o realiza una acción que crea una actividad.
2. El código recibe la actividad y el agente lo procesa mediante TurnContext.
3. El agente devuelve una o varias actividades.
4. El turno finaliza y TurnContext se elimina.

Acceda a los datos desde TurnContext, como:

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

Este fragmento de código muestra un ejemplo de un 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 de la TurnContext clase , la información clave usada habitualmente incluye:

• Actividad: la forma principal de obtener información de la actividad
• Adaptador: adaptador de canal que creó la actividad
• TurnState: el estado del turno

Tipos de actividades

El tipo de una actividad es importante, ya que define lo que es necesario o se espera en el resto de la actividad entre clientes, usuarios y agentes.

Message

Un tipo común de actividad es el tipo de mensaje de Activity, que podría incluir texto, datos adjuntos y acciones sugeridas para nombrar algunos usos comunes para este 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

El tipo ConversationUpdate de Activity notifica al agente cuando los miembros se unen o abandonan una conversación. No todos los clientes admiten esto, un cliente notable que sí es Microsoft Teams.

El siguiente fragmento de código saluda a los nuevos miembros en una conversación:

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

El tipo Evento de Activity es un evento personalizado que permite a los canales o clientes enviar datos estructurados a su agente, los cuales no están predefinidos en la estructura de la carga útil Activity.

Tendría que crear un controlador de métodos o rutas para el tipo específico Event y, a continuación, administrar la lógica deseada en función de:

Name : el nombre del evento o el identificador del valor del cliente: carga de eventos que suele ser un 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

Un tipo invoke de Activity es un tipo específico de actividad que un cliente llama a un agente para realizar un comando o una operación, y no solo un mensaje. Algunos ejemplos de estos tipos de actividades son comunes en Microsoft Teams para task/fetch y task/submit. No todos los canales admiten este tipo de actividades.

Typing

Un tipo de escritura de Activity es una clasificación de actividad para indicar que alguien está escribiendo en una conversación. Esto se suele ver entre conversaciones humanas a humanas en el cliente de Microsoft Teams, por ejemplo. Las actividades de escritura no se admiten en todos los clientes y, en particular, Microsoft 365 Copilot no admite actividades de escritura.

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

Creación y envío de actividades

Para enviar respuestas, "TurnContext" proporciona varios métodos para devolver las respuestas al usuario.

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
}

Trabajar con adjuntos

Es habitual que los agentes trabajen con datos adjuntos enviados por los usuarios (o incluso con otros agentes). El cliente envía una Message actividad que incluye datos adjuntos (no es un tipo específico de actividad) y el código debe controlar la recepción del mensaje con los datos adjuntos, leer los metadatos y capturar de forma segura el archivo de la dirección URL proporcionada por el cliente. Sería habitual mover el archivo a su almacenamiento personal.

Para recibir un archivo adjunto

En el código siguiente se muestra cómo recibir y adjuntar.

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 recibir el documento al adjunto, el cliente envía una solicitud autenticada GET para recuperar el contenido real: cada adaptador tiene su propia manera de obtener dichos datos, por ejemplo, Teams, OneDrive, etc. También es importante saber que esas direcciones URL suelen ser de corta duración y, por lo tanto, no suponga que permanecerán allí, por lo que el traslado a su propio almacenamiento es importante si necesita hacer referencia a esto más adelante.

Citas

Es importante saber que Attachment y Citation no son el mismo tipo de objeto. Las citas son gestionadas por aplicaciones cliente, como Microsoft Teams, de manera particular, y usan la propiedad Entities de Activity y pueden ser incorporadas con activity.Entities.Add, agregando un nuevo objeto Entity que tenga la definición específica Citation basada en su aplicación cliente. Se serializaría como un objeto JSON que el cliente deserializa en función de cómo se representa en el cliente. Fundamentalmente, los datos adjuntos son mensajes, y las citas pueden referirse a ellos, siendo otro objeto más enviado en Entities de la carga Activity.

Consideraciones específicas del canal

El SDK de Microsoft 365 Agents está diseñado como un 'Hub' que permite a los desarrolladores crear agentes que puedan trabajar con cualquier cliente, incluidos los clientes que admitimos, y proporciona las herramientas para que los desarrolladores puedan crear su propio adaptador de canal utilizando el mismo marco. Esto proporciona a los desarrolladores amplitud cuando se trata de agentes y proporciona extensibilidad a los clientes para conectarse a ese centro, que puede ser uno o varios clientes como Microsoft Teams, Slack y mucho más.

Los distintos canales tienen diferentes funcionalidades y limitaciones, y a continuación se muestra un resumen de las consideraciones al trabajar con clientes comunes.

Puede comprobar el canal desde el que ha recibido la actividad verificando la propiedad channelId en Activity.

Los canales incluyen datos específicos que no se ajustan a la carga genérica Activity en todos los canales y se puede acceder a ellos desde TurnContext.Activity.ChannelData y convertirlo específicamente en variables para su uso en el código.

Equipos de Microsoft

• Admite tarjetas adaptables enriquecidas con características avanzadas
• Admite actualizaciones y eliminaciones de mensajes
• Tiene datos de canal específicos para las funciones de Teams (menciones, información de reunión, etc.)
• Admite actividades de invocación para módulos de tareas

Copiloto de Microsoft 365

• Centrado principalmente en las actividades de mensajería
• Admite citas y referencias en respuestas
• Requiere respuestas de streaming
• Compatibilidad limitada con tarjetas enriquecidas o tarjetas adaptables

WebChat/DirectLine

Chat en web es un protocolo HTTP que se usa para que los agentes hablen a través de HTTPS.

• Compatibilidad completa con todos los tipos de actividad
• Admite datos de canal personalizados

Canales de terceros

Entre ellas se incluyen Slack, Facebook y mucho más.

• Es posible que tenga compatibilidad limitada con determinados tipos de actividad
• La renderización de tarjetas puede ser diferente o no compatible
• Comprobar siempre la documentación específica del canal