Inviare un evento o un'attività

2025-06-23

Copilot Studio offre un set di nodi che è possibile usare per le attività che non sono messaggi: il nodo Attività evento , il nodo Attività Invoke e altri nodi correlati all'attività supportati dal protocollo di attività .

Cos'è il protocollo di attività?

Il protocollo di attività è un concetto di trasporto fondamentale in Copilot Studio. Il protocollo di attività consente una comunicazione trasparente tra utenti e agenti. Definisce una struttura standardizzata per tutte le interazioni, classificandole in vari tipi di attività.

Le attività degli eventi e le attività dei messaggi sono due tipi distinti all'interno del protocollo di attività, ognuno dei quali serve scopi univoci nei flussi di lavoro di comunicazione.

Le attività dei messaggi rappresentano le unità di comunicazione fondamentali tra utenti e agenti, che trasportano principalmente contenuti testuali, multimediali o schede adattive. Sono progettati per interazioni dirette, in cui un utente fa una domanda o un'affermazione e l'agente risponde di conseguenza.

Le attività degli eventi, d'altra parte, vengono in genere usate per indicare azioni non verbali o aggiornamenti generati dal sistema. Consentono una comunicazione asincrona, attivando funzionalità o flussi di lavoro specifici senza richiedere l'interazione diretta dell'utente. Ad esempio, un'attività evento può notificare a un agente che un utente partecipa a una conversazione o modifiche nel contesto circostante.

Invio di eventi

Il nodo Attività evento è progettato per l'invio di attività di evento. Le attività Evento vengono inviate dall'agente e possono essere intercettate e utilizzate dal canale, che decide se e come utilizzare le attività. Quando si invia un evento, si assegna un nome e quindi è possibile impostare un valore per l'evento. Questo valore può essere in qualsiasi formato:

Valore letterale primitivo
Riferimento variabile
Formula di Power Fx.

Il valore viene serializzato come valore letterale JSON e aggiunto all'attività in uscita.

Gli usi di questo nodo includono:

Configurare un controllo Web Chat personalizzato per gestire gli eventi inviati dall'agente. Ad esempio, potresti cercare un evento proveniente dall'agente ed eseguire un'azione sulla pagina. Il 04.api/c.incoming-activity-event campione nel Repository di campioni chat Web di Microsoft Bot Framework su GitHub dimostra come potrebbe funzionare la gestione degli eventi.
Usare le attività di evento per controllare i servizi di registrazione di AudioCodes, ad esempio per avviare o arrestare la registrazione delle chiamate. Per altre informazioni, vedi Registrazione delle chiamate.

Uso degli strumenti client

Durante l'orchestrazione, viene fornito al modello linguistico un set di strumenti. La maggior parte delle persone considera gli strumenti come un modo per interagire con sistemi esterni.

Strumenti lato server tramite API.

Tuttavia, possiamo anche usare le attività evento per eseguire gli strumenti dal client.

Strumenti lato client tramite attività di tipo evento.

Quando l'agente di orchestrazione decide di eseguire uno strumento client, l'agente invia un'attività evento al client, inclusi gli input definiti nello strumento.

L'agente invia l'attività, quindi attende che il client esegua l'azione e restituisca un risultato. Al termine, il client invia un'attività evento contenente la risposta all'agente. L'agente accetta questa risposta come risposta dello strumento e continua l'orchestrazione.

Payload di esempio per gli strumenti client

Si supponga di avere uno strumento client che recupera il testo in una diapositiva di PowerPoint.

Gli input sono il numero di pagina e l'output è il testo sulla diapositiva.

L'agente potrebbe inviare un payload come:

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

Al termine dell'operazione, il client invia all'agente un payload come:

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

Configurazione degli strumenti client

Esistono due modi per registrare gli strumenti client.

Come parte del contenuto dell'argomento dell'agente, puoi registrare un'azione dell'attività client dedicata sull'agente, utilizzando l'editor di codice.

Ad esempio:

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

In alcuni casi, gli strumenti disponibili sono dinamici, in base al contesto del client di hosting. Per consentire una maggiore flessibilità, gli autori possono definire una variabile di sistema per impostare dinamicamente altri strumenti client che possono essere usati per questa sessione.

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

Invio di altri tipi di attività

Oltre alle attività di tipo evento, è possibile inviare attività di altro tipo utilizzando il nodo attività di tipo chiamata. I tipi di attività che puoi inviare sono un sottoinsieme di quelli offerti nello Bot Framework Schema - Classe ActivityTypes. Quando si utilizza questo nodo, si sceglie il tipo di attività e quindi si imposta facoltativamente un nome o un valore.

I tipi comuni sono:

Digitazione: invia un'attività di digitazione, che il canale può scegliere di raccogliere per mostrare un indicatore di digitazione sul client.
Invoke e risposta Invoke sono usati per Microsoft Teams. Si crea un argomento con un trigger di chiamata per intercettare una chiamata in ingresso da Teams e si usa un nodo di attività di risposta alla chiamata per inviare una risposta appropriata a Teams.
Passaggio invia un'attività di passaggio con controllo esplicito sul valore. Viene usato un passaggio per canali esterni, ad esempio AudioCodes.

Condividi tramite