Compartir a través de

Enviar un evento o actividad

Copilot Studio proporciona un conjunto de nodos que puede usar para las actividades que no son mensajes: el nodo Actividad de eventos, el nodo Invocar actividad y otros nodos relacionados con la actividad que admite el protocolo de actividad .

¿Qué es el protocolo de actividad?

El protocolo de actividad es un concepto de transporte central de Copilot Studio. El protocolo de actividad permite una comunicación sin problemas entre los usuarios y los agentes. Define una estructura estandarizada para todas las interacciones, clasificándolas en varios tipos de actividades.

Las actividades de eventos y las actividades de mensaje son dos tipos distintos dentro del protocolo de actividad, cada uno de los cuales sirve para propósitos únicos en los flujos de trabajo de comunicación.

Las actividades de mensaje representan las unidades de comunicación fundamentales entre los usuarios y los agentes, principalmente con contenido textual, multimedia o tarjetas adaptables. Están diseñados para interacciones directas, donde un usuario realiza una consulta o instrucción, y el agente responde en consecuencia.

Las actividades de eventos, por otro lado, se usan normalmente para indicar acciones noverbales o actualizaciones generadas por el sistema. Permiten la comunicación asíncrona, desencadenando funcionalidades o flujos de trabajo específicos sin requerir la interacción directa del usuario. Por ejemplo, una actividad de evento puede notificar a un agente sobre un usuario que se une a una conversación o cambios en el contexto circundante.

Enviando eventos

El nodo actividad de eventos está diseñado para enviar actividades de eventos. Las actividades del evento se envían desde el agente y pueden ser interceptadas y utilizadas por el canal, que decide si usar las actividades y cómo. Al enviar un evento, se le asigna un nombre y, a continuación, se puede establecer un valor para el evento. Este valor puede estar en cualquier formato:

  • Un valor literal primitivo
  • Referencia variable
  • Fórmula de Power Fx.

El valor se serializa como un literal JSON y se agrega a la actividad saliente.

Los usos de este nodo incluyen:

  • Configure un control de chat web personalizado para controlar los eventos enviados desde el agente. Por ejemplo, podría buscar un evento que regrese del agente y realizar una acción en la página. El ejemplo 04.api/c.incoming-activity-event en el Repositorio de muestras de chat web en GitHub de Microsoft Bot Framework demuestra cómo podría funcionar la gestión de eventos.
  • Use actividades de eventos para controlar los servicios de grabación audioCodes, por ejemplo, para iniciar o detener la grabación de llamadas. Para obtener más información, consulte Grabar llamadas.

Uso de herramientas de cliente

Durante la orquestación, proporcionamos el modelo de lenguaje con un conjunto de herramientas. La mayoría de las personas consideran las herramientas como llamadas a sistemas externos.

Herramientas del lado servidor a través de la API.

Sin embargo, también podemos usar actividades de eventos para ejecutar herramientas desde el cliente.

Herramientas del lado del cliente a través de actividades de eventos.

Cuando el orquestador decide ejecutar una herramienta cliente, el agente envía una actividad de evento al cliente, incluidas las entradas definidas en la herramienta.

El agente envía la actividad y, después, espera a que el cliente realice la acción y devuelva un resultado. Cuando el cliente haya terminado, envía una actividad de evento que contiene la respuesta al agente. El agente toma esta respuesta como la respuesta de la herramienta y continúa la orquestación.

Cargas de ejemplo para herramientas de cliente

Supongamos que tenemos una herramienta cliente que recupera el texto en una diapositiva de PowerPoint.

Las entradas son el número de página y la salida es el texto de la diapositiva.

El agente podría enviar una carga útil como:

{ 
    "type": "event", 
    "timestamp": 1738709828, 
    "from": { 
        "id": "d9c0dcf9-4045-8062-535b-73fb4dfee954", 
        "role": 0 
    }, 
    "name": "getSlideContent", 
    "replyToId": "f617c120-7b36-496a-a096-ac692efdad04", 
    "value": { 
        "page": 5      
    } 
}

Una vez finalizada la operación, el cliente envía al agente una carga útil como:

{ 
    "type": "event", 
    "timestamp": 1738709828, 
    "name": "getSlideContent", 
    "replyToId": "f617c120-7b36-496a-a096-ac692efdad04", 
    "value": { 
        "content": "QA slide. Next steps"      
    } 
}

Configuración de herramientas de cliente

Hay dos maneras de registrar las herramientas de cliente.

Como parte del contenido del tema de su agente, puede registrar una acción de tarea de cliente dedicada en su agente, utilizando el editor de código.

Por ejemplo:

description: this tool retrieves the content of a powerpoint slide 
schemaName: GetSlideContent 
    dialog: 
      kind: TaskDialog 
      action: 
        kind: InvokeClientTaskAction 
        clientActionInputSchema: 
          kind: Record 
          properties: 
            page: 
            displayName: Page Number 
            description: The number of the slide 
            isRequired: true 
              type: Number 
        clientActionResponseSchema: 
          kind: Record 
          properties: 
            content: 
            displayName: Slide Content 
            description: The content of the slide 
              type: String

A veces, las herramientas disponibles son dinámicas, en función del contexto del cliente de hospedaje. Para permitir una mayor flexibilidad, los creadores pueden establecer una variable de sistema para establecer dinámicamente otras herramientas cliente que se pueden usar para esta sesión.

- kind: SetVariable 
  id: setVariable_76NZWK 
  variable: System.ClientPluginActions 
  value: |- 
    =[ 
      { 
        Description: "this tool retrieves the content of a powerpoint slide", 
        Identifier: "GetSlideContent", 
        Name: "GetSlideContent", 
        Response: {mode: "Generated"}, 
        Inputs: [ 
          { 
            Description: "The name of the menu for the form to launch", 
            IsAutomatic: true, 
            IsRequired: true, 
            Name: "Page Number", 
            PropertyName: "page", 
            Type: { 
              '$kind': "Number" 
            } 
          } 
        ], 
        Outputs: [ 
          { 
            Description: "The content of the slide", 
            Name: "Slide Content", 
            PropertyName: "content", 
            Type: { 
              '$kind': "String" 
            } 
          } 
        ] 
      } 
    ]

Envío de otros tipos de actividad

Además de las actividades de eventos, puede enviar actividades de otros tipos mediante el nodo Invocar actividad. Los tipos de actividades que puede enviar son un subconjunto de los que se ofrecen en el Esquema Bot Framework - Clase de tipos de actividad. Al usar este nodo, elige el tipo de actividad y luego, opcionalmente, establece un nombre o valor.

Los tipos comunes son:

  • Mecanografía envía una actividad de mecanografía, que el canal puede elegir para recoger y mostrar un indicador de mecanografía en el cliente.
  • Invocar y Respuesta de invocación son utilizados para Microsoft Teams. Puede crear un tema con un desencadenador de invocación para interceptar una invocación entrante de Teams y usar un nodo de Actividad de invocar respuesta para enviar una respuesta adecuada a Teams.
  • Transferencia envía una actividad de transferencia con control explícito sobre el valor. Una transferencia se utiliza para canales externos, como AudioCodes.

Contenido relacionado