Compartilhar via

Enviar um evento ou atividade

O Copilot Studio oferece um conjunto de nós que você pode usar em atividades que não são mensagens: o nó Atividade do evento, o nó Atividade de invocação e outros nós relacionados à atividade compatível com o protocolo.

O que é o protocolo de atividade?

O protocolo de atividade é um conceito central de transporte no Copilot Studio. O protocolo de atividade permite uma comunicação perfeita entre usuários e agentes. Ele define uma estrutura padronizada para todas as interações, classificando-as em vários tipos de atividades.

Atividades de evento e atividades de mensagem são dois tipos distintos dentro do protocolo de atividade, cada um atendendo a finalidades exclusivas em fluxos de trabalho de comunicação.

As atividades de mensagem representam as unidades de comunicação fundamentais entre usuários e agentes, transportando principalmente conteúdo textual, de mídia ou de cartão adaptável. Eles são projetados para interações diretas, em que um usuário faz uma consulta ou instrução e o agente responde adequadamente.

As atividades de evento, por outro lado, normalmente são usadas para significar ações não verbais ou atualizações geradas pelo sistema. Eles permitem a comunicação assíncrona, acionando funcionalidades ou fluxos de trabalho específicos sem a necessidade de interação direta do usuário. Por exemplo, uma atividade de evento pode notificar um agente sobre a entrada de um usuário em uma conversa ou alterações no contexto ao redor.

Enviando eventos

O nó Atividade de evento foi projetado para enviar atividades de evento. As atividades do evento são enviadas do agente e podem ser interceptadas e usadas pelo canal, que decide se e como usar as atividades. Ao enviar um evento, você dá um nome a ele e, em seguida, pode definir um valor para o evento. Esse valor pode estar em qualquer formato:

  • Um valor literal primitivo
  • Uma referência de variável
  • Um fórmula do Power Fx.

O valor é serializado como um literal JSON e adicionado à atividade de saída.

Os usos desse nó incluem:

  • Configure um controle de Web Chat personalizado para lidar com eventos enviados do agente. Por exemplo, você pode procurar um evento voltando do agente e executar uma ação na página. O 04.api/c.incoming-activity-event exemplo no repositório de exemplos de Web Chat no GitHub do Microsoft Bot Framework mostra como a manipulação de eventos pode funcionar.
  • Use atividades de evento para controlar os serviços de gravação do AudioCodes, por exemplo, para iniciar ou parar a gravação de chamadas. Para obter mais informações, consulte Gravação de chamadas.

Usando ferramentas de cliente

Durante a orquestração, fornecemos ao modelo de linguagem um conjunto de ferramentas. A maioria das pessoas pensa em ferramentas como chamadas para sistemas externos.

Ferramentas do servidor via API.

No entanto, também podemos usar atividades de evento para executar ferramentas do cliente.

Ferramentas do lado do cliente por meio das atividades de evento.

Quando o orquestrador decide executar uma ferramenta de cliente, o agente envia uma atividade de evento para o cliente, incluindo as entradas definidas na ferramenta.

O agente envia a atividade e, em seguida, aguarda que o cliente execute a ação e retorne um resultado. Quando termina, o cliente envia uma atividade de evento contendo a resposta para o agente. O agente considera essa resposta como a resposta da ferramenta e continua o processo de orquestração.

Conteúdos de amostra para ferramentas de cliente

Suponha que tenhamos uma ferramenta de cliente que recupere o texto em um slide do PowerPoint.

As entradas são o número da página e a saída é o texto no slide.

O agente pode enviar um conteúdo 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      
    } 
}

Após a conclusão da operação, o cliente envia ao agente um conteúdo como:

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

Configurando ferramentas de cliente

Há duas maneiras de registrar ferramentas de cliente.

Como parte do conteúdo do tópico do agente, você pode registrar uma ação de tarefa de cliente dedicada no agente, usando o editor de códigos.

Por exemplo: 

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

Às vezes, as ferramentas disponíveis são dinâmicas, com base no contexto do cliente de hospedagem. Para permitir mais flexibilidade, os criadores podem definir uma variável de sistema para definir dinamicamente outras ferramentas de cliente que podem ser usadas para esta sessão.

- 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" 
            } 
          } 
        ] 
      } 
    ]

Enviando outros tipos de atividade

Além das atividades de evento, você pode enviar atividades de outros tipos usando o nó Atividade de invocação. Os tipos de atividades que podem ser enviados são um subconjunto daqueles oferecidos no Esquema do Bot Framework - Classes de ActivityTypes. Ao usar esse nó, você escolhe o tipo de atividade e, opcionalmente, define um nome ou valor.

Os tipos comuns são:

  • Digitação - envia uma atividade de digitação, que o canal pode escolher para selecionar e mostrar um indicador de digitação no cliente.
  • A invocação e a resposta de invocação são usadas para o Microsoft Teams. Você cria um tópico com um gatilho de invocação para interceptar uma Chamada de entrada do Teams e usa um nó Chamar atividade de resposta para enviar uma resposta apropriada de volta ao Teams.
  • Entrega envia uma atividade de entrega com controle explícito sobre o valor. Uma entrega é usada para canais externos, como o AudioCodes.

Conteúdo relacionado

  • Last updated on