Skip to content
FundamentalsStandard HarnessLab 05

Lab 05 - Device Request Agent Flows ​

Tempo stimato: ~90 minuti · Harness: standard

Scenario ​

I dispositivi aziendali di Zava (laptop, desktop, smartphone) sono censiti in una lista SharePoint con stato, produttore, modello e dati di acquisto. Oggi un collega che ha bisogno di un nuovo dispositivo deve chiedere quali sono disponibili e poi scrivere al proprio manager: l'IT vuole che tutto avvenga in chat, con una richiesta che arriva al manager già completa.

In questo lab si crea l'agente Device Booker: un topic legge dalla lista SharePoint i dispositivi disponibili del tipo richiesto, un secondo topic li propone in una adaptive card e passa la scelta a un agent flow, che recupera il dispositivo e invia l'email di richiesta al manager.

Che cosa si costruisce ​

Il primo schema mostra i componenti dell'agente Device Booker alla fine del lab: i topic gestiscono la conversazione con l'utente, l'agent flow esegue in Power Automate i passi che non la richiedono.

AGENTE DEVICE BOOKERAGENT FLOW · SEND DEVICE REQUEST EMAILWhen an agent calls the flowinput DeviceSharePointId, User,AdditionalComments (facoltativo)Respond to the agentoutput ModelValue = Model
Passa il mouse su un riquadro o selezionalo per vederne il dettaglio.

Il secondo schema segue una richiesta dall'inizio alla fine: è la stessa conversazione da provare nella sezione Testing.

Sequenza di una richiesta: l'utente chiede un laptop, Available devices legge la lista Devices, Request device mostra l'adaptive card, l'agent flow recupera il dispositivo, invia l'email al manager e restituisce ModelValueUtenteDevice BookerAgent flowLista Devices1a new laptopi want to request2Available devices:VarDeviceType Laptop3Get items: Status Available, AssetType Laptop4Global.VarDevices5richiederne uno?Laptop disponibili;6Sì7adaptive cardRequest device:8dispositivo e commentiSubmit Request:9request emailSend device10Get item per IDGet Device:11Model, linkManufacturer,12Send an emailto manager13ModelValue14inviata al managerThanks: richiesta

Prerequisiti ​

Per svolgere questo lab occorre avere:

  • completato il Lab 01 (developer environment e solution CSMFirstAgent come preferred solution);
  • il sito SharePoint Help Desk CSM creato nel Lab 02, con la lista Devices descritta qui sotto;
  • una casella di posta Office 365 Outlook nel proprio account, per ricevere l'email della richiesta.

Lista SharePoint Devices ​

Per lo svolgimento di questo Lab è necessario avere il Sito SharePoint del Lab 02 - Knowledge Sources. Usare la Lista chiamata Devices presente di default nel Sito generato con il Template e aggiungere le seguenti colonne:

  • Title
  • Status
  • Manufacturer
  • Model
  • Asset Type
  • Color
  • Serial Number
  • Purchase Date
  • Purchase Price
  • Order #

Ricreare la lista basandosi su questa tabella:

TitleStatusManufacturerModelAsset TypeColorSerial NumberPurchase DatePurchase PriceOrder #
Fabrikam Laptop X1AvailableFabrikam, Inc.FX1-2023LaptopSpace grayFAB1234567892023-10-03T22:00:00Z1,199.00ORD101
Microsoft Surface Laptop 5AvailableMicrosoftSurface Laptop 5LaptopSilverMSL5001122332024-03-12T23:00:00Z1,499.00ORD107
Microsoft Surface Laptop Studio 2AvailableMicrosoftSurface Laptop Studio 2LaptopBlackMSLS220045672024-09-17T22:00:00Z2,399.00ORD108
Contoso Phone ZIn useContoso, Ltd.CP-Z2022SmartphoneSilverCON5566778892023-01-19T23:00:00Z699.00ORD103
Trey Smartphone EliteAvailableTrey ResearchTS-E2025SmartphoneDark blueTREY5566007782025-01-14T23:00:00Z899.00ORD109
Contoso Desktop ProAvailableContoso, Ltd.CDP-900DesktopBlackCOND3344556672024-06-04T22:00:00Z1,299.00ORD110

Gli stessi dati sono nel file:

Creazione Agente ​

  1. Navigare all'interno di Copilot Studio e selezionare Agents nel menù laterale a sinistra.

  2. Nella schermata Agents è possibile visualizzare la lista completa degli agenti creati nell'environment; proseguire premendo Create blank agent.

  1. Copilot Studio procederà con la creazione dell'agente vuoto: per effettuare modifiche aspettare il seguente messaggio:

  1. Finito il provisioning dell'agente modificare Nome e Descrizione:
  • Nome:
Device Booker
  • Descrizione:
Automatically manages device reservations, availability, and assignments across the asset lifecycle.
  1. Lasciare le istruzioni vuote per il momento e proseguire con la guida.

Creazione Topic - Available Devices ​

Il topic completo, come apparirà nel canvas alla fine della sezione: legge la lista Devices e restituisce all'agente i dispositivi disponibili del tipo richiesto.

TOPIC · AVAILABLE DEVICESTriggerThe agent chooses, dalla descrizione:dispositivi disponibili nella lista DevicesGlobal.VarDevices
Passa il mouse su un riquadro o selezionalo per vederne il dettaglio.
  1. Andare nella sezione Topics, selezionare Add a topic e poi From blank.

  1. Cambiare il nome del topic con:
Available devices
  1. Inserire la seguente descrizione del trigger:
This topic helps users find devices that are available from our SharePoint Devices list. User can ask to see available devices and it will return a list of devices that are available which can include laptops, smartphones, accessories and more.

Successivamente, verrà aggiunta una nuova variabile di input che l’IA generativa utilizzerà durante il processo di orchestrazione per estrarre, dal messaggio dell’utente, il valore relativo al tipo di dispositivo.

  1. Selezionare i tre puntini (…) accanto al topic, quindi scegliere Details per visualizzare il pannello dei dettagli del topic.

  1. Il pannello Topic details è ora stato caricato. Selezionare la scheda Input.

  1. Selezionare Create a new variable.

  1. Inserire il nome della variabile:
VarDeviceType
  1. Cambiare Identify as in User's entire response.

  1. Modificare la descrizione della variabile in:
List of possible values: Laptop, Desktop, Smartphone

  1. Andare nella sezione Output e creare una nuova variabile.

  1. Inserire i seguenti dati:
  • Variable name
VarAvailableDevices
  • Variable data type :  Table

  • Variable description :

List of available devices by device type

  1. Ora terminati i dettagli del Topic premere l'icona del + e aggiungere un nuovo nodo.

  1. Selezionare Add a tool, andare nella sezione Connector e cercare il connettore Get items di SharePoint.

  1. Selezionare la tab Input e inserire il sito SharePoint creato in precedenza, con la lista Devices.

  2. Ora aprire il menù a tendina delle Advanced Options e in filter Query premere il simbolo (...).

  1. Recarsi nella sezione Formula e inserire la seguente espressione Power Fx:
Concatenate("Status eq 'Available' and AssetType eq '", Topic.VarDeviceType, "'")

Nota

Filtro dinamico

La formula costruisce dinamicamente una stringa di filtro unendo testo fisso con il valore di Topic.VarDeviceType. Il risultato è una query che seleziona solo i dispositivi con stato "Available" e tipo uguale al valore della variabile.

  1. Premere Insert.

  1. Selezionare poi All items in Limit Columns by View.

  1. Ora modificare il nome della variabile di Output in:
VarDevices
  1. Modificarla da variabile di Topic a Global.

  1. Successivamente aggiungere un nuovo nodo Variable Management -> Set a variable value.

  1. Selezionare per il Set a variable la variabile VarAvailableDevices.

  1. Premere l'icona (...) nella sezione To value.

  1. Selezionare la sezione Formula e inserire la seguente espressione:
Global.VarDevices.value
  1. Premere Insert.

Creazione Topic - Request device ​

Creare un nuovo Topic che guiderà l'utente nella prenotazione di un dispositivo.

Il topic completo, alla fine di questa sezione e delle due successive: l'agent flow si crea e si aggiunge dopo l'adaptive card.

TOPIC · REQUEST DEVICETriggerThe agent chooses, dalla descrizione: l'utenterisponde sì alla richiesta di un dispositivodeviceSelectionId · commentsIdModelValueMessageThanks, User.DisplayName. Your selecteddevice, ModelValue, has been submittedRedirectGo to another topic: End of Conversation
Passa il mouse su un riquadro o selezionalo per vederne il dettaglio.
  1. Andare nella sezione Topics, selezionare Add a topic e poi From blank.

  1. Cambiare il nome del topic con:
Request device
  1. Inserire la seguente descrizione del trigger:
This topic helps users request a device when they answer yes to the question that asks the user if they would like to request one of these devices.

  1. Successivamente premere il + e selezionare Ask with adaptive card.

  1. Selezionare il nodo e nelle Properties premere Edit adaptive card.

All’interno dell’editor del Card payload, selezionare l’intero contenuto utilizzando la combinazione di tasti Ctrl + A su Windows oppure Command + A su Mac, quindi procedere con l’eliminazione delle righe selezionate. Successivamente, incollare il JSON:

{
    "type": "AdaptiveCard",
    "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "backgroundImage": {
        "url": "https://adaptivecards.io/content/backgroundImage.png",
        "verticalAlignment": "Center"
    },
    "body": [
        {
            "type": "Container",
            "style": "emphasis",
            "bleed": true,
            "items": [
                {
                    "type": "TextBlock",
                    "text": "Device selection",
                    "weight": "Bolder",
                    "size": "Large",
                    "wrap": true
                }
            ]
        },
        {
            "type": "Container",
            "style": "default",
            "items": [
                {
                    "type": "TextBlock",
                    "text": "Please select which device you would like to request:",
                    "wrap": true,
                    "size": "Medium"
                }
            ],
            "spacing": "None"
        },
        {
            "type": "Container",
            "spacing": "None",
            "items": [
                {
                    "type": "Input.ChoiceSet",
                    "id": "deviceSelectionId",
                    "style": "expanded",
                    "choices": [
                        {
                            "title": "Laptop - Dell XPS 13",
                            "value": "1"
                        },
                        {
                            "title": "Desktop - HP EliteDesk 800",
                            "value": "2"
                        },
                        {
                            "title": "Tablet - Microsoft Surface Pro",
                            "value": "3"
                        },
                        {
                            "title": "Smartphone - iPhone 15 Pro",
                            "value": "4"
                        },
                        {
                            "title": "Smartphone - Samsung Galaxy S23",
                            "value": "5"
                        }
                    ]
                }
            ]
        },
        {
            "type": "Container",
            "spacing": "None",
            "style": "emphasis",
            "items": [
                {
                    "type": "TextBlock",
                    "text": "Additional Information",
                    "wrap": true
                },
                {
                    "type": "Input.Text",
                    "id": "commentsId",
                    "placeholder": "Please provide any specific requirements or comments",
                    "isMultiline": true,
                    "spacing": "Small"
                }
            ]
        },
        {
            "type": "Container",
            "spacing": "Medium",
            "items": [
                {
                    "type": "FactSet",
                    "facts": [
                        {
                            "title": "Request type:",
                            "value": "New Device"
                        },
                        {
                            "title": "Response time:",
                            "value": "3-5 Business Days"
                        }
                    ],
                    "spacing": "Small"
                }
            ]
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Submit Request"
        }
    ]
}

Questo JSON rappresenta attualmente un segnaposto e un’anteprima di quello che verrà utilizzato come base per la scheda, ma sotto forma di formula anziché di JSON, poiché verrà fatto riferimento alla variabile globale Global.VarDevices.value, che memorizza la risposta dell’azione del connettore SharePoint Get items.

  1. Salvare e chiudere la card.

Scorrendo fino in fondo al nodo, sono visibili le variabili di output. commentsId e deviceSelectionId sono due variabili che memorizzano i valori provenienti dagli elementi della scheda con cui gli utenti interagiscono. Tali valori verranno utilizzati nelle fasi successive del flow.

  1. Ora modificare la Card trasformandola in Formula card.

  1. Sostituire la Card premendo Ctrl + A su Windows o Command + A su Mac e incollare questo:
{
  type: "AdaptiveCard",
  '$schema': "https://adaptivecards.io/schemas/adaptive-card.json",
  version: "1.5",
  backgroundImage: {
    url: "https://adaptivecards.io/content/backgroundImage.png",
    verticalAlignment: "Center"
  },
  body: [
    {
      type: "Container",
      style: "emphasis",
      bleed: true,
      items: [
        {
          type: "TextBlock",
          text: "Device selection",
          weight: "Bolder",
          size: "Large",
          wrap: true
        }
      ]
    },
    {
      type: "Container",
      style: "default",
      items: [
        {
          type: "TextBlock",
          text: "Please select which device you would like to request:",
          wrap: true,
          size: "Medium"
        }
      ],
      spacing: "None"
    },
    {
      type: "Container",
      spacing: "None",
      items: [
        {
          type: "Input.ChoiceSet",
          id: "deviceSelectionId",
          style: "expanded",
          choices: ForAll(Global.VarDevices.value,
            {
              title: If(IsBlank(Model), "NA", Model),
              value: If(IsBlank(ID), "NA", ID)
            }
          )
        }
      ]
    },
    {
      type: "Container",
      spacing: "None",
      style: "emphasis",
      items: [
        {
          type: "TextBlock",
          text: "Additional Information",
          wrap: true
        },
        {
          type: "Input.Text",
          id: "commentsId",
          placeholder: "Please provide any specific requirements or comments",
          isMultiline: true,
          spacing: "Small"
        }
      ]
    },
    {
      type: "Container",
      spacing: "Medium",
      items: [
        {
          type: "FactSet",
          facts: [
            {
              title: "Request type:",
              value: "New Device"
            },
            {
              title: "Response time:",
              value: "3-5 Business Days"
            }
          ],
          spacing: "Small"
        }
      ]
    }
  ],
  actions: [
    {
      type: "Action.Submit",
      title: "Submit Request",
      id: "deviceSubmittedId"
    }
  ]
}
Come si legge la formula

Restituisce le opzioni della scheda: una scelta per ogni dispositivo letto da SharePoint.

  • Global.VarDevices.value: la tabella dei dispositivi restituita da Get items.
  • ForAll(tabella, { ... }): ripete la formula per ogni riga e restituisce una tabella con un record per riga.
  • title: If(IsBlank(Model), "NA", Model): il testo mostrato. Dentro ForAll i nomi Model e ID sono le colonne della riga corrente; se il valore manca si usa "NA".
  • value: If(IsBlank(ID), "NA", ID): il valore restituito alla scelta, che finisce in deviceSelectionId.

Risultato: un'opzione per dispositivo, con il modello come testo e l'ID come valore.

  1. Salvare il Topic.

Creazione Flow ​

Nel Topic Request device, andare sotto all'Adaptive card e premere il simbolo + per aggiungere un nuovo nodo.

  1. Selezionare Add a tool -> Basic tools -> New Agent Flow.

Il Designer degli Agent flow verrà caricato con un trigger e un’azione.

Trigger – Quando un agente richiama il flow
Questo attiverà un flow da un agente di Copilot Studio.

Azione – Rispondere all’agente
Questa operazione invia una risposta che può contenere valori di output all’agente di Copilot Studio.

  1. Selezionare il trigger.

  1. Premere Add an input e selezionare Text.

  1. Compilare il nome dell'input con:
DeviceSharePointId

  1. Ora aggiungere un secondo input sempre testuale. Impostare il nome con:
User

  1. Infine aggiungere un ultimo input testuale:
AdditionalComments

Per AdditionalComments impostare il campo come facoltativo premendo il simbolo (...) e poi Make the field optional

  1. Aggiungere sotto al trigger un nuovo nodo, cercare Get Item di SharePoint.

  1. Selezionare il simbolo (...) e poi rinominare il tool con:
Get Device

  1. Nei campi Site Address e List Name inserire il sito e la lista SharePoint creati in precedenza. Nel campo Id inserire tramite il simbolo fx il Dynamic Content DeviceSharePointId relativo al trigger.

  1. Successivamente in Advanced parameters premere Show All.

  1. In Limit Columns by View selezionare All items.

  1. Successivamente premere l'icona del + sotto il Get Device tool e cercare send an email. Selezionare Send an email (V2) tool di Office 365 Outlook connector.

  1. Rinominare il Tool in:
Send an email to manager
  1. Nella sezione To selezionare il proprio account.

  2. Per la sezione Subject inserire:

Request type: new device
  1. Per il Body:
Hi,

New device requested from [USER PLACEHOLDER]

Manufacturer: [MANUFACTURER PLACEHOLDER]
Model: [MODEL PLACEHOLDER]
Link to item in SharePoint 
Additional comments from [USER PLACEHOLDER]: 

This is an automated email from an Agent

  1. Come prossimo punto inserire nel Body tramite il simbolo del fulmine i Dynamic Content segnati in CAPS tra parentesi quadre.

  1. Per il link di SharePoint è necessario aprire l'editor HTML con l'icona </>.

Premere prima di "Link to item in SharePoint" e aggiungere:

<a href="

Premere dopo le " e inserire come Dynamic Content dal Get Item di SharePoint il Link to Item.

Inserire questo dopo il Dynamic Content del Link:

">

Successivamente inserire dopo la scritta "Link to item in SharePoint":

</a>

Con questo è terminato l'inserimento dell'hyperlink per SharePoint: premere l'icona </> per uscire dall'editor.

  1. Infine non resta che inserire una funzione per la sezione di Additional Comments. Selezionare uno spazio vuoto dopo i : e premere il simbolo fx.

Inserire nel box funzione:

if(empty())

Dopo inserire come Dynamic Content l'input AdditionalComments dal trigger del Flow.

Successivamente dopo la parentesi inserire:

, 'None',

Come ultimo punto inserire nuovamente dopo l'ultima virgola il Dynamic Content AdditionalComments.

Nota

Commenti facoltativi

La formula verifica se il campo AdditionalComments del trigger è vuoto. Se è vuoto restituisce il valore "None", altrimenti restituisce il contenuto.

  1. Selezionare il nodo "Respond to the agent" e inserire come Output testuale:
ModelValue

Come valore inserire il contenuto dinamico Model del nodo Get item.

  1. Il Flow è terminato, ora non resta che salvare: premere Save draft. Andare su Overview e selezionare Edit.

Inserire nome e descrizione del Flow:

  • Name:
Send device request email
  • Description:
This flow starts when an agent manually triggers it and provides device and user details. It retrieves device information from a SharePoint list using the provided device ID. After successfully getting the device details, it sends an email to a manager with the request information, and sends a value back to the agent.

  1. Tornare sul Designer e premere Publish.

Aggiungere il Flow al Topic ​

Per aggiungere il Flow appena creato al Topic "Request device" selezionare Agents nel menù presente a sinistra.

  1. Selezionare l'agente Device Booker, andare su Topics e selezionare "Request device".

  1. Andare sotto al nodo Ask with adaptive card, premere il + e selezionare Add a tool e successivamente il Flow appena creato.

  1. Premere il simbolo (...) del primo campo e selezionare deviceSelectionId.

  1. Dopo nel campo user inserire User.DisplayName.

  1. Premere > per espandere la sezione Advanced Inputs, selezionare il simbolo (...) e successivamente la sezione Formula.

Inserire la seguente formula fx:

If(IsBlank(Topic.commentsId), "", Topic.commentsId)

Nota

Commenti vuoti

La formula verifica se il campo Topic.commentsId è vuoto (Blank()). Se lo è, restituisce una stringa vuota (""), altrimenti restituisce il valore di commentsId. Serve a evitare valori NULL in output che potrebbero causare errori in controlli o funzioni. In pratica, converte un valore vuoto in una stringa vuota utilizzabile.

  1. Premere il + dopo il nodo "Action" del Flow e inserire un nodo Send a message con il seguente contenuto:
Thanks, [User.DisplayName]. 
Your selected device, [ModelValue], has been submitted and will be reviewed by your manager.

Dove i contenuti fra parentesi quadre devono essere sostituiti con le variabili corrispondenti.

  1. Inserire sotto un nuovo nodo. Selezionare Topic Management poi Go to another Topic e infine End of Conversation.

  1. Salvare il Topic.

Istruzioni ​

Prima di procedere con i test sull'agente è necessario inserire le istruzioni.

  1. Andare su Overview, selezionare edit nel box Instructions e inserire le seguenti istruzioni:
# Context

Device Booker is an agent that allows users to see available devices and request devices from a SharePoint Device Inventory List. The agent interacts only with SharePoint Lists to retrieve device availability information and to submit device booking requests.

# Action

[Available device]  -> Used to view the list of devices that are currently marked as Available in the SharePoint Device Inventory List before making a booking request.  
[Request device]  -> Used to submit a request for a device that is currently available in the SharePoint Device Inventory List by specifying device details and booking dates.

# Rules

The agent can only read available devices and create device requests in the SharePoint Lists.  
The agent cannot approve requests, modify inventory manually, manage maintenance status, or process device returns.    
The agent must use a professional and concise tone when interacting with users.
  1. Sostituire i Topic segnati fra parentesi quadre tramite il / e selezionando il Topic corrispondente.

  1. Premere Save per salvare le Istruzioni.

Testing ​

Iniziare una nuova sessione nella finestra di Test, selezionare il simbolo (...) e spuntare Track between topics.

Testare il funzionamento dell'agente richiedendo un dispositivo, qui sotto un esempio:

i want to request a new laptop

Proseguire con il test a piacere.

Importante

Lab Completato

L'agente Device Booker ora mostra i dispositivi disponibili e invia al manager la richiesta di quello scelto. In questo lab si è visto:

  • come leggere una lista SharePoint da un topic con il connettore Get items e un filtro in Power Fx;
  • come passare dati tra topic con variabili globali e di output;
  • come costruire una adaptive card dinamica con una Formula card;
  • come creare un agent flow con input, azioni SharePoint e Outlook e un output per l'agente;
  • come richiamare l'agent flow da un topic e usarne la risposta.