Creare agenti dichiarativi usando Microsoft 365 Agents Toolkit e TypeSpec

Un agente dichiarativo offre un'esperienza di conversazione orientata agli obiettivi basata su Microsoft 365 Copilot. Ne definisci lo scopo, le istruzioni, le conoscenze e le azioni. Questa guida illustra come creare un agente dichiarativo usando TypeSpec e Microsoft 365 Agents Toolkit.

Nota

L'agente creato in questa esercitazione è destinato agli utenti di Microsoft 365 Copilot con licenza. È anche possibile creare agenti per gli utenti di Microsoft 365 Copilot Chat, con funzionalità limitate. Per informazioni dettagliate, vedi Licenze per sviluppatori di Microsoft 365 Copilot.

Suggerimento

Consigliato: Inizia con Work IQ Dev Tools per scenari di agenti dichiarativi e plug-in pro-code supportati. Vedere la guida introduttiva di WIQD. Le istruzioni basate su toolkit rimangono disponibili per i progetti e i flussi di lavoro esistenti che le richiedono. Controlla il supporto per le funzionalità e l'esperienza di destinazione prima di scegliere uno strumento: WIQD non si rivolge agli agenti del motore personalizzato.

Nota

Gli agenti dichiarativi basati su Microsoft 365 Copilot sono ora supportati in Word e PowerPoint.

Prerequisiti

  • Un tenant di Microsoft 365 in cui è possibile caricare app personalizzate. Il provisioning non riesce se il caricamento dell'app personalizzata non è abilitato. Per abilitare il caricamento di app personalizzate, vedi Requisiti di Microsoft 365 Agents Toolkit. Per l'ambiente di sviluppo e le opzioni di licenza, vedere Ambiente di sviluppo Copilot.

Per completare i passaggi descritti in questo articolo, sono necessarie le risorse seguenti:

Nota

Gli screenshot e i riferimenti all'interfaccia utente in questo articolo usano una versione finale di Microsoft 365 Agents Toolkit. Le versioni non definitive potrebbero differire dall'interfaccia utente visualizzata.

Scopri gli standard e le linee guida seguenti per gli agenti dichiarativi di Microsoft 365 Copilot:

Creare un agente dichiarativo

Per iniziare, creare un agente dichiarativo di base.

  1. Apri Visual Studio Code.

  2. Selezionare Microsoft 365 Agents Toolkit > Crea un nuovo agente/app.

    Screenshot del pulsante Crea una nuova app nella barra laterale del Toolkit agenti di Microsoft 365

  3. Selezionare Agente dichiarativo.

    Screenshot delle opzioni di Nuovo progetto con l'opzione Agente selezionata

  4. Selezionare Inizia con TypeSpec per Microsoft 365 Copilot per creare un agente dichiarativo di base.

  5. Selezionare Cartella predefinita per archiviare la cartella principale del progetto nella posizione predefinita.

  6. Immetti My Agent come nome dell'applicazione e premi INVIO.

  7. Nella nuova finestra di Visual Studio Code che si apre, seleziona Microsoft 365 Agents Toolkit. Nel riquadro Ciclo di vita selezionare Provisioning.

    Screenshot dell'opzione Provisioning nel riquadro Ciclo di vita del Toolkit agenti di Microsoft 365

Testare l'agente

  1. Vai all'applicazione Copilot all'indirizzo https://m365.cloud.microsoft/chat.

  2. Accanto al pulsante Nuova chat, seleziona l'icona del cassetto della conversazione.

  3. Selezionare l'agente dichiarativo My Agent.

    Screenshot dell'agente dichiarativo in Copilot

  4. Immettere una domanda per l'agente dichiarativo per vederla in azione.

Aggiungere istruzioni

Le istruzioni cambiano il comportamento di un agente.

  1. Apri il main.tsp file e sostituisci l'elemento @instructions decoratore con il codice seguente.

    @instructions("""
      You are an expert at creating poems.
      Every time a user asks a question, you **must** turn the answer into a poem. The poem **must** not use the quote markdown and use regular text.
    """)
    

    Il processo di provisioning inserisce il contenuto di questo decoratore nella instructions proprietà nel manifesto dell'agente. Per ulteriori informazioni, vedere Oggetto manifesto agente dichiarativo.

  2. Seleziona Provisioning nel pannello Ciclo di vita di Agents Toolkit.

L'agente dichiarativo usa le istruzioni aggiornate dopo aver ricaricato la pagina.

Screenshot di una risposta di un agente dichiarativo basata su istruzioni aggiornate

Aggiungi gli spunti di conversazione

Gli spunti di conversazione sono suggerimenti che Copilot mostra agli utenti per mostrare come iniziare a usare l'agente dichiarativo.

  1. Apri il main.tsp file e sostituisci l'elemento decoratore commentato @conversationStarter con il contenuto seguente:

    @conversationStarter(#{
      title: "Getting started",
      text: "How can I get started with Agents Toolkit?"
    })
    
    @conversationStarter(#{
      title: "Getting Help",
      text: "How can I get help with Agents Toolkit?"
    })
    

    Per ulteriori informazioni, vedere Oggetto Conversation Starters.

  2. Seleziona Provisioning nel pannello Ciclo di vita di Agents Toolkit.

Gli spunti di conversazione aggiornati sono disponibili nell'agente dichiarativo dopo l'aggiornamento della pagina.

Screenshot che mostra gli spunti di conversazione dall'agente dichiarativo in Microsoft 365 Copilot

Aggiungere contenuti Web

La funzionalità di ricerca Web consente agli agenti di usare l'indice di ricerca in Bing per rispondere alle richieste degli utenti.

  1. Apri il main.tsp file e aggiungi la WebSearch funzionalità nello MyAgent spazio dei nomi con il contenuto seguente.

    namespace MyAgent {
      op webSearch is AgentCapabilities.WebSearch<Sites = [
        {
          url: "https://learn.microsoft.com",
        },
      ]>;
    }
    

    Per ulteriori informazioni, vedere Oggetto di ricerca Web.

    Nota

    Se non si specifica l'array Sites , l'agente può accedere a tutti i contenuti web.

  2. Seleziona Provisioning nel pannello Ciclo di vita di Agents Toolkit.

L'agente dichiarativo può accedere al contenuto Web per generare le sue risposte dopo aver ricaricato la pagina.

Screenshot che mostra una risposta dell'agente dichiarativo che include contenuto Web

Aggiungere contenuto di OneDrive e SharePoint

La funzionalità SharePoint consente all'agente di usare il contenuto di OneDrive e SharePoint come conoscenza.

  1. Aprire il main.tsp file e aggiungere la OneDriveAndSharePointMyAgent funzionalità nello spazio dei nomi con il valore seguente, sostituendola https://contoso.sharepoint.com/sites/ProductSupport con un URL del sito di SharePoint nell'organizzazione di Microsoft 365.

    namespace MyAgent {
      // Omitted for brevity
      op od_sp is AgentCapabilities.OneDriveAndSharePoint<ItemsByUrl = [
        {
          url: "https://contoso.sharepoint.com/sites/ProductSupport"
        }
      ]>;
      // Omitted for brevity
    }
    

    Per altre informazioni, vedere OneDrive e oggetto SharePoint.

    Nota

    • Gli URL devono essere il percorso completo degli elementi di SharePoint (sito, raccolta documenti, cartella o file). È possibile usare l'opzione "Copia collegamento diretto" in SharePoint per ottenere il percorso completo o i file e le cartelle. Fai clic con il pulsante destro del mouse sul file o sulla cartella e seleziona Dettagli. Passa a Percorso e seleziona l'icona di copia.
    • Se non si specifica la ItemsByUrl matrice (o la matrice alternativa ItemsBySharePointIds ), l'agente può accedere a tutti i contenuti di OneDrive e SharePoint dell'organizzazione di Microsoft 365 a cui l'utente connesso può accedere.
  2. Seleziona Provisioning nel pannello Ciclo di vita di Agents Toolkit.

L'agente dichiarativo ha accesso al contenuto di OneDrive e SharePoint per generare le risposte dopo aver ricaricato la pagina.

Screenshot che mostra una risposta dell'agente dichiarativo che contiene il contenuto di SharePoint e OneDrive

Aggiungere messaggi di Teams

La funzionalità messaggi di Teams consente all'agente di usare i canali, il team e la chat delle riunioni di Teams come conoscenza.

  1. Aprire il main.tsp file e aggiungere la TeamsMessages funzionalità nello MyAgent spazio dei nomi con il valore seguente, sostituendola https://teams.microsoft.com/l/team/... con un canale di Teams o un URL del team dell'organizzazione.

    namespace MyAgent {
      // Omitted for brevity
      op teamsMessages is AgentCapabilities.TeamsMessages<TeamsMessagesByUrl = [
        {
          url: "https://teams.microsoft.com/l/team/...",
        }
      ]>;
      // Omitted for brevity
    }
    

    Per altre informazioni, vedere Oggetto messaggi di Microsoft Teams.

    Nota

    • L'URL nella url proprietà deve essere un collegamento ben formato a una chat, un team o una chat di riunione di Teams.
    • Se non si specifica la matrice, l'agente può accedere a tutti i canali, i team, le TeamsMessagesByUrl riunioni, le chat individuali e le chat di gruppo dell'organizzazione di Microsoft 365 a cui l'utente autenticato può accedere.
  2. Seleziona Provisioning nel pannello Ciclo di vita di Agents Toolkit.

L'agente dichiarativo può accedere ai dati di Teams per generare le risposte dopo aver ricaricato la pagina.

Screenshot che mostra una risposta dell'agente dichiarativo che contiene il contenuto di Teams

Aggiungi le informazioni sulle persone

La funzionalità Persone consente di definire l'ambito dell'agente per rispondere a domande sugli utenti di un'organizzazione.

  1. Apri il main.tsp file e aggiungi la People funzionalità nello MyAgent spazio dei nomi con il contenuto seguente.

    namespace MyAgent {
      // Omitted for brevity
      op people is AgentCapabilities.People;
      // Omitted for brevity
    }
    

    Per ulteriori informazioni, vedere Oggetto People.

  2. Seleziona Provisioning nel pannello Ciclo di vita di Agents Toolkit.

L'agente dichiarativo ha accesso alle conoscenze delle persone dopo aver ricaricato la pagina.

Screenshot che mostra una risposta dell'agente dichiarativo che contiene le informazioni sugli utenti

Aggiungi informazioni sulla posta elettronica

La funzionalità di posta elettronica consente di definire l'ambito dell'agente in modo che utilizzi la posta elettronica proveniente dalla cassetta postale dell'utente o da una cassetta postale condivisa come origine delle informazioni.

  1. Apri il main.tsp file e aggiungi la Email funzionalità nello MyAgent spazio dei nomi con il contenuto seguente.

    namespace MyAgent {
      // Omitted for brevity
      op email is AgentCapabilities.Email<Folders = [
        {
          folder_id: "Inbox",
        }
      ]>;
      // Omitted for brevity
    }
    

    Per ulteriori informazioni, vedere Oggetto Email.

    Nota

    • Questo esempio accede all'utente della cassetta postale dell'agente. Per accedere invece a una cassetta postale condivisa, aggiungere la proprietà facoltativa shared_mailbox impostata sull'indirizzo di posta elettronica della cassetta postale condivisa.
    • La Folders matrice limita l'accesso della cassetta postale a cartelle specifiche. Per accedere all'intera cassetta postale, omettere la folders matrice.
  2. Seleziona Provisioning nel pannello Ciclo di vita di Agents Toolkit.

L'agente dichiarativo ha accesso alle conoscenze della posta elettronica dopo aver ricaricato la pagina.

Screenshot che mostra una risposta dell'agente dichiarativo che contiene le informazioni sulla posta elettronica

Aggiungi generatore di immagini

La funzionalità di generazione di immagini consente agli agenti di generare immagini in base alle richieste dell'utente.

  1. Apri il main.tsp file e aggiungi la GraphicArt funzionalità nello MyAgent spazio dei nomi con il contenuto seguente.

    namespace MyAgent {
      // Omitted for brevity
      op graphicArt is AgentCapabilities.GraphicArt;
      // Omitted for brevity
    }
    

    Per ulteriori informazioni, consultate Oggetto grafica.

  2. Seleziona Provisioning nel pannello Ciclo di vita di Agents Toolkit.

L'agente dichiarativo può generare immagini dopo aver ricaricato la pagina.

Screenshot che mostra una risposta dell'agente dichiarativo che contiene l'immagine grafica generata

Aggiungi interprete di codice

La funzionalità dell'interprete di codice è uno strumento avanzato progettato per risolvere compiti complessi attraverso il codice Python.

  1. Apri il main.tsp file e aggiungi la CodeInterpreter funzionalità nello MyAgent spazio dei nomi con il contenuto seguente.

    namespace MyAgent {
      // Omitted for brevity
      op codeInterpreter is AgentCapabilities.CodeInterpreter;
      // Omitted for brevity
    }
    

    Per ulteriori informazioni, consultate Oggetto Interprete del codice.

  2. Seleziona Provisioning nel pannello Ciclo di vita di Agents Toolkit.

L'agente dichiarativo dispone della funzionalità di interprete del codice dopo aver ricaricato la pagina.

Screenshot che mostra una risposta dell'agente dichiarativo che contiene un grafico generato

Screenshot che mostra il codice Python usato per generare il grafico richiesto

Aggiungere il contenuto dei connettori Copilot

Aggiungere gli elementi acquisiti da un connettore Copilot alle informazioni disponibili per l'agente.

  1. Aprire il main.tsp file e aggiungere la GraphConnectors funzionalità nello MyAgent spazio dei nomi con il valore seguente, sostituendola policieslocal con un ID connettore Copilot valido nell'organizzazione di Microsoft 365. Per altre informazioni su come trovare gli ID dei connettori Copilot, vedere Recuperare gli ID delle funzionalità per il manifesto dell'agente dichiarativo.

    namespace MyAgent {
      // Omitted for brevity
      op copilotConnectors is AgentCapabilities.GraphConnectors<Connections = [
        {
          connectionId: "policieslocal",
        }
      ]>;
      // Omitted for brevity
    }
    

    Per altre informazioni, vedere Oggetto connettori Copilot.

    Nota

    Se non si specifica la matrice, l'agente ottiene il Connections contenuto da tutti i connettori Copilot nell'organizzazione di Microsoft 365 a cui l'utente connesso può accedere.

  2. Seleziona Provisioning nel pannello Ciclo di vita di Agents Toolkit.

L'agente dichiarativo può accedere al contenuto dei connettori Copilot per generare le risposte dopo aver ricaricato la pagina.

Screenshot che mostra una risposta dell'agente dichiarativo che contiene il contenuto del connettore Copilot

Completato/Eseguito

È stata completata la guida dell'agente dichiarativo per Microsoft 365 Copilot. Ora che hai familiarità con l'uso di TypeSpec per creare un agente dichiarativo, puoi saperne di più negli articoli seguenti.

Passaggi successivi