Partilhar via

Enviar um evento ou atividade

O Copilot Studio fornece um conjunto de nós que pode utilizar para atividades que não são mensagens: o nó Atividade de Evento, o nó Invocar atividade e outros nós relacionados com atividades que o protocolo de atividade suporta.

O que é o protocolo de atividade?

O protocolo de atividade é um conceito de transporte central 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, categorizando-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 servindo propósitos exclusivos em fluxos de trabalho de comunicação.

As atividades de mensagem representam as unidades de comunicação fundamentais entre utilizadores e agentes, e incluem principalmente conteúdo textual, de multimédia ou de cartão adaptável. Eles são projetados para interações diretas, onde um usuário faz uma consulta ou instrução e o agente responde de acordo.

As atividades de eventos, por outro lado, são normalmente 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 exigir interação direta do usuário. Por exemplo, uma atividade de evento pode notificar um agente sobre a participação de um usuário em uma conversa ou alterações no contexto ao redor.

Enviar eventos

O nó Atividade de evento foi concebido para enviar atividades de evento. As atividades de evento são enviadas pelo agente e podem ser intercetadas e utilizadas pelo canal, que decide se e como utilizar as atividades. Quando envia um evento, atribui-lhe um nome e, em seguida, pode definir um valor para o evento. Este valor pode estar em qualquer formato:

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

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

As utilizações deste nó incluem:

  • Configure um controle de Web Chat personalizado para manipular eventos enviados pelo agente. Por exemplo, pode procurar um evento que regresse do agente e execute uma ação na página. O 04.api/c.incoming-activity-event exemplo no repositório de exemplos do Microsoft Bot Framework Web Chat no GitHub demonstra como a manipulação de eventos pode funcionar.
  • Use atividades de eventos para controlar os serviços de gravação AudioCodes, por exemplo, para iniciar ou interromper 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 lado do servidor através de API.

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

Ferramentas do lado do cliente através de atividades de evento.

Quando o orquestrador decide executar uma ferramenta 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, espera que o cliente execute a ação e retorne um resultado. Quando o cliente termina, envia uma atividade de evento que contém a resposta para o agente. O agente toma essa resposta como a resposta da ferramenta e continua a orquestração.

Exemplos de payloads para ferramentas de cliente

Suponha que temos uma ferramenta de cliente que recupera 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 payload 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 concluir a operação, o cliente envia ao agente um pacote de dados, como um payload:

{ 
    "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 de tópico de agente, pode registar uma ação de tarefa dedicada do cliente no seu agente, utilizando o editor de código.

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

Enviar outros tipos de atividade

Além das atividades de evento, pode enviar atividades de outros tipos utilizando o nó Invocar atividade. Os tipos de atividades que você pode enviar são um subconjunto dos oferecidos no Bot Framework Schema - ActivityTypes Class. Ao usar esse nó, você escolhe o tipo de atividade e, opcionalmente, define um nome ou valor.

Os tipos comuns são:

  • Digitar envia uma atividade de digitação, que o canal pode escolher captar e exibir um indicador de digitação no cliente.
  • Invoke e Invoke response são usados para o Microsoft Teams. Cria um tópico com um acionador de invocação para intercetar uma Invocação de entrada do Teams e utiliza um nó Invocar atividade de resposta para enviar uma resposta apropriada de volta ao Teams.
  • Handoff envia uma atividade de transferência com controle explícito sobre o valor. Uma entrega é utilizada para canais externos, como AudioCodes.

Conteúdo relacionado