Descripción del protocolo de actividad

El protocolo de actividad es un protocolo de comunicación standard que se usa en Microsoft en muchos SDK, servicios y clientes de Microsoft. El protocolo de actividad lo usan Microsoft 365 Copilot, Microsoft Copilot Studio y el SDK de agentes de Microsoft 365. El Protocolo de Actividad define la estructura de un Activity y cómo fluyen los mensajes, los eventos y las interacciones de un canal a tu código y a cualquier otro punto 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 con cualquier cliente con el que esté trabajando, incluidos los clientes Microsoft y no Microsoft, de modo que no tenga que crear lógica personalizada para cada canal.

¿Qué es una actividad?

es Activity un objeto JSON estructurado que representa cualquier interacción entre un usuario y tu agente. Las actividades no se limitan a los mensajes basados en texto. Pueden incluir varios tipos de interacción, como eventos como la unión o la salida de un usuario para clientes que admiten varios usuarios, indicadores de escritura, cargas de archivos, acciones de tarjeta y eventos personalizados que diseñan los desarrolladores.

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:

Acceso a datos de actividad

Para completar las acciones del TurnContext objeto, los desarrolladores deben acceder a los datos dentro de la actividad.

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

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

El TurnContext es un objeto importante que se utiliza en cada turno de conversación en el 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. Úselo 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 de Agentes crea una instancia nueva de TurnContext y la pasa a los controladores 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 y que llega a tu código. El código controla esos datos y, opcionalmente, puede devolver una respuesta para completar el turno. Ese recorrido de ida y vuelta se puede dividir en los pasos siguientes:

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 actividad

El tipo de una actividad define lo que el resto de la actividad requiere o espera entre clientes, usuarios y agentes.

Entre ellas se incluyen las siguientes:

• Message
• Actualización de Conversación
• Evento
• Invoke
• Typing

Message

Un tipo común de actividad es el tipo de mensaje de Activity. Este Activity tipo puede incluir texto, datos adjuntos y acciones 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);
});

Actualización de Conversación

El tipo ConversationUpdate de Activity notifica al agente cuando los miembros se unen o dejan una conversación. No todos los clientes admiten esta notificación, pero Microsoft Teams sí.

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

Events

El tipo de Evento de Activity es un evento personalizado que los canales o clientes utilizan para enviar datos estructurados a su agente. Estos datos no están predefinidos en la estructura de Activity payload.

Debe crear un método o un controlador de ruta para el tipo específico Event . A continuación, administre la lógica deseada en función de:

• Nombre: el nombre del evento o el identificador del cliente
• Valor: carga de eventos que normalmente es 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. No es sólo 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 estos tipos 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. Esta actividad se suele ver en conversaciones entre humanos en el cliente de Microsoft Teams, por ejemplo. Las actividades de tecleo no están soportadas en todos los clientes. 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

Los agentes suelen trabajar con datos adjuntos que envían los usuarios (o incluso otros agentes). El cliente envía una Message actividad que incluye datos adjuntos (no es un tipo específico de actividad). 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. Normalmente, mueves el archivo a tu propio almacenamiento.

Para recibir un archivo adjunto

En el código siguiente se muestra cómo recibir datos adjuntos.

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 relacionado con los datos adjuntos, el cliente envía una solicitud autenticada GET para recuperar el contenido real. Cada adaptador tiene su propia manera de obtener esos datos. Por ejemplo, Teams, OneDrive, etc. También es importante saber que esas direcciones URL suelen ser de corta duración y, por tanto, no supongan que las direcciones URL permanecen válidas durante mucho tiempo. Esta limitación es la razón por la que pasar a su propio almacenamiento es importante si necesita hacer referencia al contenido más adelante.

Citas

Es importante saber que Attachment y Citation no son el mismo tipo de objeto. Los clientes, como Microsoft Teams, controlan las citas de sus propias maneras. Usan la propiedad Entities del Activity. Puede agregar citas con activity.Entities.Add y agregar un nuevo Entity objeto que tenga la definición específica Citation basada en el cliente. Se serializa 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 estos y constituyen otro objeto enviado dentro del Entities de la Activity carga.

Consideraciones específicas del canal

El SDK de agentes de Microsoft 365 se crea como una "plataforma" que los desarrolladores usan para crear agentes que pueden trabajar con cualquier cliente, incluidos los clientes que admitimos. Proporciona las herramientas para que los desarrolladores creen su propio adaptador de canal mediante el mismo marco. Esta arquitectura 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, etc.

Los diferentes canales tienen diferentes funcionalidades y limitaciones.

Puede comprobar el canal desde el que recibió la actividad inspeccionando la channelId propiedad en .Activity

Los canales incluyen datos específicos que no se ajustan a la carga genérica Activity en todos los canales. Puede acceder a estos datos desde la TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) propiedad mediante la conversión a variables para su uso en el código.

En las secciones siguientes se resumen las consideraciones al trabajar con clientes comunes.

Equipos de Microsoft

• Soporta Tarjetas adaptables ricas en funcionalidad con características avanzadas.
• Admite actualizaciones y eliminaciones de mensajes.
• Tiene datos de canal específicos para las características de Teams, como menciones e información de reunión.
• Admite actividades de invocación para módulos de tareas.

Copiloto de Microsoft 365

• Se centra principalmente en las actividades de mensajería.
• Admite citas y referencias en respuestas.
• Requiere respuestas en transmisión.
• Compatibilidad limitada con tarjetas enriquecidas y tarjetas adaptables.

Chat en web/DirectLine

Chat en web es un protocolo HTTP que los agentes pueden usar para comunicarse a través de HTTPS.

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

Canales que no son de Microsoft

Estos canales incluyen Slack, Facebook y mucho más.

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

Pasos siguientes

• Más información sobre AgentApplication