Esercizio - Restituire risposte avanzate con schede adattive

9 minuti

Si inizierà creando modelli di schede adattive per consentire all'agente di visualizzare i dati nelle risposte. Per compilare il modello di scheda adattiva, è possibile usare le estensioni di Visual Studio Code del visualizzatore di schede adattive per visualizzare facilmente in anteprima il lavoro direttamente in Visual Studio Code. L'uso dell'estensione consente di compilare un modello di scheda adattiva, con riferimenti ai dati. In fase di esecuzione, l'agente riempie il segnaposto con i dati recuperati dall'API.

Scaricare il progetto iniziale

Per iniziare, scaricare il progetto di esempio. In un Web browser:

Vai a https://github.com/microsoft/learn-declarative-agent-api-plugin-adaptive-cards-typescript.
Se si dispone di un account GitHub:
1. Selezionare Usa questo elenco a discesa modello e scegliere Crea un nuovo repository dal menu.
2. Nell'elenco dei proprietari disponibili scegliere l'account.
3. Assegnare al repository il nome da-ristorante-api.
4. Confermare la creazione del repository usando il pulsante Crea repository .
5. Attendere che GitHub crei il repository. Copiare quindi l'URL del repository.
6. Aprire una riga di comando.
7. In una riga di comando modificare la directory di lavoro in cui si vuole archiviare il progetto nel disco.
8. Clonare il repository usando il comando seguente: git clone https://github.com/your-user/your-repo.
9. Aprire la cartella clonata in Visual Studio Code.
Se non si ha un account GitHub:
1. Scaricare il contenuto del repository come zip.
2. Estrarre il contenuto del file ZIP sul disco.
3. Aprire la cartella in Visual Studio Code.

Il progetto di esempio è un progetto di Microsoft 365 Agents Toolkit che include un agente dichiarativo con un'azione compilata con un plug-in API. Il plug-in API si connette a un'API anonima in esecuzione in Funzioni di Azure incluso anche nel progetto. L'API appartiene a un ristorante italiano fittizio e consente di sfogliare il menu di oggi e di effettuare ordini.

Creare una scheda adattiva per un piatto

Creare prima di tutto una scheda adattiva che mostra le informazioni su un singolo piatto.

In Visual Studio Code:

Nella visualizzazione Esplora risorse creare una nuova cartella denominata cards.
Nella cartella cards creare un nuovo file denominato dish.json. Incollare il contenuto seguente che rappresenta una scheda adattiva vuota:
```
{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": []
}
```

Prima di continuare, creare un file di dati per la scheda adattiva:

Aprire il riquadro comandi premendo CTRL+P (CMD+P in macOS) sulla tastiera. Digitare >Adaptive per trovare i comandi correlati all'uso delle schede adattive.
Nell'elenco scegliere Scheda adattiva: Nuovo file di dati. Visual Studio Code crea un nuovo file denominato dish.data.json.

Sostituire il contenuto con un dato che rappresenta un piatto:

{
  "id": 4,
  "name": "Caprese Salad",
  "description": "Juicy vine-ripened tomatoes, fresh mozzarella, and fragrant basil leaves, drizzled with extra virgin olive oil and a touch of balsamic.",
  "image_url": "https://raw.githubusercontent.com/pnp/copilot-pro-dev-samples/main/samples/da-ristorante-api/assets/caprese_salad.jpeg",
  "price": 10.5,
  "allergens": [
    "dairy"
  ],
  "course": "lunch",
  "type": "dish"
}

Save your changes

Indietro al file dish.json.
Nell'obiettivo selezionare Anteprima scheda adattiva.

Visual Studio Code apre un'anteprima della scheda sul lato. Durante la modifica della scheda, le modifiche sono immediatamente visibili sul lato.
Alla matrice del corpo aggiungere un elemento Container con un riferimento all'URL dell'immagine archiviato nella proprietà image_url .
```
{
  "type": "Container",
  "items": [
    {
      "type": "Image",
      "url": "${image_url}",
      "size": "large"
    }
  ]
}
```
Si noti che l'anteprima della scheda viene aggiornata automaticamente per mostrare la scheda:

Aggiungere riferimenti ad altre proprietà del piatto. La scheda completa è la seguente:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "Image",
          "url": "${image_url}",
          "size": "large"
        },
        {
          "type": "TextBlock",
          "text": "${name}",
          "weight": "Bolder"
        },
        {
          "type": "TextBlock",
          "text": "${description}",
          "wrap": true
        },
        {
          "type": "TextBlock",
          "text": "Allergens: ${if(count(allergens) > 0, join(allergens, ', '), 'none')}",
          "weight": "Lighter"
        },
        {
          "type": "TextBlock",
          "text": "**Price:** €${formatNumber(price, 2)}",
          "weight": "Lighter",
          "spacing": "None"
        }
      ]
    }
  ]
}

Si noti che per visualizzare gli allergeni si usa una funzione per unire gli allergeni in una stringa. Se un piatto non ha allergeni, non ne viene visualizzato alcuno. Per assicurarsi che i prezzi siano formattati correttamente, si usa la funzione formatNumber che consente di specificare il numero di decimali da visualizzare nella scheda.

Compilare una scheda adattiva per il riepilogo dell'ordine

L'API di esempio consente agli utenti di esplorare il menu e di effettuare un ordine. Si creerà una scheda adattiva che mostra il riepilogo degli ordini.

In Visual Studio Code:

Nella cartella cards creare un nuovo file denominato order.json. Incollare il contenuto seguente che rappresenta una scheda adattiva vuota:
```
{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": []
}
```
Creare un file di dati per la scheda adattiva:
1. Aprire il riquadro comandi premendo CTRL+P (CMD+P in macOS) sulla tastiera. Digitare >Adaptive per trovare i comandi correlati all'uso delle schede adattive.
2. Nell'elenco scegliere Scheda adattiva: Nuovo file di dati. Visual Studio Code crea un nuovo file denominato order.data.json.
3. Sostituire il contenuto con i dati che rappresentano il riepilogo dell'ordine:
```
{
  "order_id": 6210,
  "status": "confirmed",
  "total_price": 25.48
}
```
4. Save your changes
Indietro al file order.json.
Nell'obiettivo selezionare Anteprima scheda adattiva.

Sostituire quindi il contenuto del file order.json con il codice seguente:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    {
      "type": "TextBlock",
      "text": "Order Confirmation 🤌",
      "size": "Large",
      "weight": "Bolder",
      "horizontalAlignment": "Center"
    },
    {
      "type": "Container",
      "items": [
        {
          "type": "TextBlock",
          "text": "Your order has been successfully placed!",
          "weight": "Bolder",
          "spacing": "Small"
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Order ID:",
              "value": "${order_id} "
            },
            {
              "title": "Status:",
              "value": "${status}"
            },
            {
              "title": "Total Price:",
              "value": "€${formatNumber(total_price, 2)}"
            }
          ]
        }
      ]
    }
  ]
}

Proprio come nella sezione precedente, ogni elemento della scheda viene mappato a una proprietà di dati.

Importante

Si noti lo spazio finale dopo ${order_id}. Ciò è intenzionale, a causa di un problema noto con i numeri di rendering delle schede adattive. Per testarlo, rimuovere lo spazio e verificare che il numero scompaia dall'anteprima.

Ripristinare lo spazio finale in modo che la scheda venga visualizzata correttamente e salvare le modifiche.

Aggiornare la definizione del plug-in API

Il passaggio finale consiste nell'aggiornare la definizione del plug-in API con le schede adattive che Copilot deve usare per visualizzare i dati dall'API agli utenti.

Aggiungere una scheda adattiva per visualizzare un piatto

In Visual Studio Code:

Aprire il file cards/dish.json e copiarne il contenuto.
Aprire il file appPackage/ai-plugin.json .
Alla proprietà functions.getDishes.capabilities.response_semantics aggiungere una nuova proprietà denominata static_template e impostarne il contenuto sulla scheda adattiva.

Il frammento di codice completo è simile al seguente:

{
  "$schema": "https://aka.ms/json-schemas/copilot/plugin/v2.1/schema.json",
  "schema_version": "v2.1",
  "namespace": "ilristorante",
  "name_for_human": "Il Ristorante",
  "description_for_human": "See the today's menu and place orders",
  "description_for_model": "Plugin for getting the today's menu, optionally filtered by course and allergens, and placing orders",
  "functions": [
    {
      "name": "getDishes",
      "description": "Returns information about the dishes on the menu. Can filter by course (breakfast, lunch or dinner), name, allergens, or type (dish, drink).",
      "capabilities": {
        "response_semantics": {
          "data_path": "$.dishes",
          "properties": {
            "title": "$.name",
            "subtitle": "$.description"
          },
          "static_template": {
            "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
            "type": "AdaptiveCard",
            "version": "1.5",
            "body": [
                ...trimmed for brevity
            ]
          }
        }
      }
    },
    {
      "name": "placeOrder",
      "description": "Places an order and returns the order details",
      "capabilities": {
        "response_semantics": {
          "data_path": "$",
          "properties": {
            "title": "$.order_id",
            "subtitle": "$.total_price"
          }
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "OpenApi",
      "auth": {
        "type": "None"
      },
      "spec": {
        "url": "apiSpecificationFile/ristorante.yml"
      },
      "run_for_functions": [
        "getDishes",
        "placeOrder"
      ]
    }
  ],
  "capabilities": {
    "localization": {},
    "conversation_starters": []
  }
}

Salvare le modifiche.

Aggiungere un modello di scheda adattiva per visualizzare il riepilogo dell'ordine

In Visual Studio Code:

Aprire il file cards/order.json e copiarne il contenuto.
Aprire il file appPackage/ai-plugin.json .
Alla proprietà functions.placeOrder.capabilities.response_semantics aggiungere una nuova proprietà denominata static_template e impostarne il contenuto sulla scheda adattiva.

Il file completo è simile al seguente:

{
  "$schema": "https://aka.ms/json-schemas/copilot/plugin/v2.1/schema.json",
  "schema_version": "v2.1",
  "namespace": "ilristorante",
  "name_for_human": "Il Ristorante",
  "description_for_human": "See the today's menu and place orders",
  "description_for_model": "Plugin for getting the today's menu, optionally filtered by course and allergens, and placing orders",
  "functions": [
    {
      "name": "getDishes",
      "description": "Returns information about the dishes on the menu. Can filter by course (breakfast, lunch or dinner), name, allergens, or type (dish, drink).",
      "capabilities": {
        "response_semantics": {
          "data_path": "$.dishes",
          "properties": {
            "title": "$.name",
            "subtitle": "$.description"
          },
          "static_template": {
            "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
            "type": "AdaptiveCard",
            "version": "1.5",
            "body": [
                ...trimmed for brevity
            ]
          }
        }
      }
    },
    {
      "name": "placeOrder",
      "description": "Places an order and returns the order details",
      "capabilities": {
        "response_semantics": {
          "data_path": "$",
          "properties": {
            "title": "$.order_id",
            "subtitle": "$.total_price"
          },
          "static_template": {
            "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
            "type": "AdaptiveCard",
            "version": "1.5",
            "body": [
                ...trimmed for brevity
            ]
          }
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "OpenApi",
      "auth": {
        "type": "None"
      },
      "spec": {
        "url": "apiSpecificationFile/ristorante.yml"
      },
      "run_for_functions": [
        "getDishes",
        "placeOrder"
      ]
    }
  ],
  "capabilities": {
    "localization": {},
    "conversation_starters": []
  }
}

Salvare le modifiche.

Testare l'agente dichiarativo con il plug-in API in Microsoft 365 Copilot

Il passaggio finale consiste nel testare l'agente dichiarativo con il plug-in API in Microsoft 365 Copilot.

In Visual Studio Code:

Nella barra delle attività scegliere Microsoft 365 Agents Toolkit.
Nella sezione Account assicurarsi di aver eseguito l'accesso al tenant di Microsoft 365 con Microsoft 365 Copilot.
Nella barra attività scegliere Esegui ed esegui debug.
Selezionare la configurazione Debug in Copilot e avviare il debug usando il pulsante Avvia debug .
Visual Studio Code compila e distribuisce il progetto nel tenant di Microsoft 365 e apre una nuova finestra del Web browser.

Nel Web browser:

Quando richiesto, accedere con l'account che appartiene al tenant di Microsoft 365 con Microsoft 365 Copilot.
Nella barra laterale selezionare Il Ristorante.
Scegliere l'avvio della conversazione What's for lunch today? (Cosa c'è per il pranzo oggi) e inviare la richiesta.
Quando richiesto, esaminare i dati inviati dall'agente all'API e confermare l'uso del pulsante Consenti una volta .
Attendere che l'agente risponda. Si noti che il popup in una citazione include ora la scheda adattiva personalizzata con informazioni aggiuntive dall'API.
Effettuare un ordine digitando nella casella di testo del prompt: 1 spaghetti, 1 tè ghiacciato e inviare il prompt.
Esaminare i dati inviati dall'agente all'API e continuare a usare il pulsante Conferma .
Attendere che l'agente inserisci l'ordine e restituisca il riepilogo dell'ordine. Si noti che, poiché l'API restituisce un singolo elemento, l'agente lo esegue il rendering usando una scheda adattiva e include la scheda direttamente nella relativa risposta.
Indietro a Visual Studio Code e arrestare il debug.
Passare alla scheda Terminale e chiudere tutti i terminali attivi.

Commenti e suggerimenti

Questa pagina è stata utile?