Delen via

Een gebeurtenis of activiteit verzenden

Copilot Studio biedt een set knooppunten die u kunt gebruiken voor activiteiten die geen berichten zijn: het knooppunt Gebeurtenisactiviteit , het knooppunt Activiteit aanroepen en andere activiteitsgerelateerde knooppunten die door het activiteitsprotocol worden ondersteund.

Wat is het activiteitenprotocol?

Het activiteitenprotocol is een kernconcept voor transport in Copilot Studio. Het activiteitenprotocol maakt naadloze communicatie mogelijk tussen gebruikers en agents. Er wordt een gestandaardiseerde structuur gedefinieerd voor alle interacties en deze worden gecategoriseerd in verschillende activiteitstypen.

Gebeurtenisactiviteiten en berichtactiviteiten zijn twee verschillende typen binnen het activiteitenprotocol, die elk unieke doeleinden in communicatiewerkstromen dienen.

Berichtactiviteiten vertegenwoordigen de fundamentele communicatie-eenheden tussen gebruikers en agents, en dragen voornamelijk tekstuele, media- of adaptieve kaartinhoud over. Ze zijn ontworpen voor directe interacties, waarbij een gebruiker een query of instructie maakt en de agent dienovereenkomstig reageert.

Gebeurtenisactiviteiten worden daarentegen meestal gebruikt om non-verbale acties of door het systeem gegenereerde updates aan te duiden. Ze maken asynchrone communicatie mogelijk, waarbij specifieke functionaliteiten of workflows worden geactiveerd zonder dat er directe interactie met de gebruiker nodig is. Een gebeurtenisactiviteit kan een agent bijvoorbeeld op de hoogte stellen van de deelname van een gebruiker aan een gesprek of van veranderingen in de context.

Gebeurtenissen verzenden

Het knooppunt Gebeurtenisactiviteit is ontworpen voor het verzenden van gebeurtenisactiviteiten. Gebeurtenisactiviteiten worden verzonden via de agent en kunnen worden onderschept en gebruikt door het kanaal, dat beslist of en hoe de activiteiten moeten worden gebruikt. Wanneer u een gebeurtenis verzendt, geeft u deze een naam en kunt u vervolgens een waarde voor de gebeurtenis instellen. Deze waarde kan een willekeurige indeling hebben:

  • Een primitieve letterlijke waarde
  • Een variabeleverwijzing
  • Een Power Fx-formule.

De waarde wordt geserialiseerd als een letterlijke JSON-waarde en toegevoegd aan de uitgaande activiteit.

Dit knooppunt kan onder meer voor het volgende worden gebruikt:

  • Configureer een aangepast webchat-besturingselement voor het afhandelen van gebeurtenissen die vanuit de agent worden verzonden. U kunt bijvoorbeeld zoeken naar een gebeurtenis die terugkomt van de agent en een actie ondernemen op de pagina. Het 04.api/c.incoming-activity-event-voorbeeld in de Microsoft Bot Framework-opslagplaats voor Webchat-voorbeelden op GitHub laat zien hoe gebeurtenisafhandeling kan werken.
  • Gebruik gebeurtenisactiviteiten om audiocodes-opnameservices te beheren, bijvoorbeeld om de opname van gesprekken te starten of te stoppen. Zie Gesprekken opnemen voor meer informatie.

Clienthulpprogramma's gebruiken

Tijdens de orkestratie voorzien we het taalmodel van een reeks hulpmiddelen. De meeste mensen denken aan hulpprogramma's als het aanroepen van externe systemen.

Hulpprogramma's aan de serverzijde via API.

We kunnen echter ook gebeurtenisactiviteiten gebruiken om hulpprogramma's van de client uit te voeren.

Hulpmiddelen aan de clientzijde via gebeurtenisactiviteiten.

Wanneer de orchestrator besluit een clienthulpprogramma uit te voeren, verzendt de agent een gebeurtenisactiviteit naar de client, inclusief de invoer die in het hulpprogramma is gedefinieerd.

De agent verstuurt de activiteit en wacht vervolgens tot de client de actie uitvoert en een resultaat retourneert. Wanneer de client klaar is, stuurt deze een gebeurtenisactiviteit met het antwoord naar de agent. De agent beschouwt dit antwoord als de respons voor het hulpmiddel en gaat verder met de orkestratie.

Voorbeeldpayloads voor clienthulpmiddelen

Stel dat we een clienthulpprogramma hebben waarmee de tekst op een PowerPoint-dia wordt opgehaald.

De invoer is het paginanummer en de uitvoer is de tekst op de dia.

De agent zou een payload kunnen sturen zoals:

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

Nadat de bewerking is voltooid, stuurt de client zoiets als een payload naar de agent, zoals:

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

Clienthulpprogramma's instellen

Er zijn twee manieren om clienthulpprogramma's te registreren.

U kunt als onderdeel van de inhoud van uw agentonderwerp een speciale clienttaakactie op uw agent registreren met behulp van de code-editor.

Bijvoorbeeld: 

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

Soms zijn de beschikbare hulpprogramma's dynamisch, op basis van de context van de hostingclient. Voor meer flexibiliteit kunnen makers een systeemvariabele instellen om dynamisch andere clienttools in te stellen die voor deze sessie kunnen worden gebruikt.

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

Andere soorten activiteiten verzenden

Naast gebeurtenisactiviteiten kunt u ook andere typen activiteiten verzenden met behulp van het knooppunt Activiteit aanroepen. De typen activiteiten die u kunt verzenden zijn een subset van de activiteiten die worden aangeboden in het Bot Framework-schema -ActivityTypes-klasse. Wanneer u dit knooppunt gebruikt, kiest u het type activiteit en stelt u vervolgens desgewenst een naam of waarde in.

Veelvoorkomende typen:

  • Typen: hiermee wordt een typeactiviteit verzonden die het kanaal kan kiezen om een type-indicator op de client op te halen en weer te geven.
  • Aanroepen en Antwoord aanroepen worden gebruikt voor Microsoft Teams. U maakt een onderwerp met een aanroeptrigger om een inkomende Aanroep vanuit Teams te onderscheppen en gebruikt een knooppunt van het type Respons aanroepen-activiteit om een passend antwoord terug te sturen naar Teams.
  • Overdracht verstuurt een overdrachtactiviteit met expliciete controle over de waarde. Een overdracht wordt gebruikt voor externe kanalen, zoals AudioCodes.

Gerelateerde inhoud

  • Last updated on