Comprender el protocolo de actividad

Protocolo de actividad es un protocolo de comunicación estándar utilizado en muchos SDK, servicios y clientes de Microsoft. El Protocolo de actividad lo utilizan Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams y el SDK de agentes de Microsoft 365. Protocolo de actividad define la estructura de una Activity y cómo los mensajes, eventos e interacciones fluyen desde un canal hasta tu código y a todos los lugares intermedios. Los agentes pueden conectarse a uno o más canales para interactuar con los usuarios y trabajar con otros agentes. El Protocolo de Actividad estandariza el protocolo de comunicación con cualquier cliente con el que trabaje, incluidos los clientes de Microsoft y de terceros, evitando que tenga que crear lógica específica para cada canal.

¿Qué es una actividad?

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

Cada actividad incluye metadatos sobre:

  • Quién la envió (remitente)
  • Quién debería recibirla (destinatario)
  • El contexto de la conversación
  • El canal del que procedía
  • El tipo de interacción
  • Los datos de la carga útil

Esquema de actividad - propiedades clave

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

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

Acceder a los datos de actividad

Para completar acciones desde el objeto TurnContext, los desarrolladores necesitan acceder a los datos dentro de la actividad.

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

Nota

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

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, la administración del estado de la conversación y el contexto necesario para gestionar un único turno de conversación. Úselo para mantener el contexto, enviar respuestas adecuados e interactuar eficazmente con sus usuarios en su cliente o canal. Cada vez que tu agente recibe una nueva actividad de un canal, el SDK de Agentes crea una nueva instancia de TurnContext y la pasa a tus controladores o métodos registrados. Este objeto de contexto existe durante un solo turno y luego se elimina una vez que termina el turno.

Un turno se define como el recorrido de ida y vuelta de un mensaje enviado desde el cliente y que llega a su código. Tu código gestiona esos datos y puede, opcionalmente, enviar una respuesta para completar el turno. Ese viaje de ida y vuelta puede desglosarse en los siguientes pasos:

  1. Actividad entrante: el usuario envía un mensaje o realiza una acción que crea una actividad.

  2. Su código recibe la actividad y el agente la procesa usando TurnContext.

  3. Su agente envía una o más actividades como respuesta.

  4. El turno termina y el TurnContext es eliminado.

Acceder 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);
});

En la clase TurnContext, la información clave utilizada habitualmente incluye:

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

Tipos de actividades

El tipo de una actividad define los requisitos o expectativas para el resto de la actividad en la interacción entre clientes, usuarios y agentes.

Incluyen:

  • Mensaje
  • ConversationUpdate
  • Evento
  • Invoke
  • Escritura

Mensaje

Un tipo común de actividad es el tipo Mensaje de Activity. Este tipo de Activity puede incluir texto, archivos 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);
});

ConversationUpdate

El tipo ConversationUpdate de Activity notifica al agente cuando los miembros se unen o abandonan 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);
            }
        }
    }
})

Eventos

El tipo 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 la carga útil Activity.

Debe crear un método o controlador de rutas para el tipo Event específico. A continuación, administre la lógica que desee basándose en:

  • Nombre: nombre o identificador del evento que envía el cliente
  • Valor: carga útil del evento que típicamente 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 es Activity un tipo específico de actividad que un cliente llama a un agente para realizar un comando u operación. No es solo un mensaje. 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.

Escritura

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 observa habitualmente en conversaciones entre personas en el cliente de Microsoft Teams, por ejemplo. Las actividades de escritura no se admiten en todos los clientes. Cabe destacar que 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);

Crear y enviar 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 archivos adjuntos que los usuarios (o incluso otros agentes) envían. El cliente envía una actividad Message que incluye un archivo adjunto (no es un tipo específico de actividad). Su código debe encargarse de recibir el mensaje con el archivo adjunto, leer los metadatos y recuperar de forma segura el archivo desde la URL que proporcionó el cliente. Por lo general, se transfiere el archivo a un almacenamiento propio.

Para recibir un archivo adjunto

El siguiente código muestra cómo recibir un archivo adjunto.

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 forma de obtener esos datos. Por ejemplo, Teams, OneDrive, etcétera. También es importante saber que esas URL suelen ser de corta duración, así que no suponga que seguirán siendo válidas durante mucho tiempo. Esta limitación es la razón por la que migrar el contenido a su propio almacenamiento es importante si necesita acceder a él más adelante.

Citas

Es importante saber que Datos adjuntos y Cita no son el mismo tipo de objeto. Los clientes, como Microsoft Teams, gestionan las citas a su manera. Usa la propiedad Entities del Activity. Puede agregar citas con activity.Entities.Add y agregar un nuevo objeto Entity que tenga la definición Citation específica según su cliente. Se serializa como un objeto JSON que el cliente luego deserializa según cómo se renderiza 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.

Configuraciones específicas de canal

El SDK de Agentes de Microsoft 365 está diseñado como un "Centro" que los desarrolladores utilizan para crear agentes que pueden trabajar con cualquier cliente, incluidos los clientes que admitimos. Ofrece las herramientas para que los desarrolladores creen su propio adaptador de canal utilizando el mismo marco de trabajo. Esta arquitectura proporciona a los desarrolladores versatilidad en el trabajo con agentes y ofrece extensibilidad para que los clientes se conecten a ese centro, que puede incluir uno o más clientes como Microsoft Teams, Slack y más.

Los diferentes canales tienen distintas capacidades y limitaciones.

Puede comprobar el canal desde el que recibió la actividad inspeccionando 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. Puede acceder a estos datos desde la propiedad TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) convirtiéndolos a variables para usarlos en su código.

Las siguientes secciones resumen las consideraciones al trabajar con clientes comunes.

Microsoft Teams

  • Admite Tarjetas adaptables enriquecidas con características avanzadas.
  • Admite actualizaciones y eliminaciones de mensajes.
  • Contiene datos específicos de los canales sobre funciones de Teams, como menciones e información sobre reuniones.
  • Admite actividades de invocación para módulos de tareas.

Microsoft 365 Copilot

  • Centrado principalmente en actividades de mensajes.
  • Admite citas y referencias en las respuestas.
  • Requiere respuestas por transmisión continua.
  • Soporte limitado para 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.

  • Soporte completo para todos los tipos de actividad.
  • Admite datos de canal personalizados.

Canales que no son de Microsoft

Estos canales incluyen Slack, Facebook y más.

  • El soporte para ciertos tipos de actividad podría ser limitado.
  • El renderizado de las tarjetas puede ser diferente o no estar admitido.
  • Consulte siempre la documentación específica del canal.

Pasos siguientes

  • Last updated on