Test agent utilizzando l'SDK Microsoft Agent 365

Testa il tuo agente localmente usando Agents Playground prima del deployment. Questa guida tratta la configurazione dell'ambiente di sviluppo, l'autenticazione e la validazione delle funzionalità del tuo agente utilizzando lo strumento di test Agents Playground.

Una volta che il tuo agente lavora localmente, puoi seguire il ciclo di vita di Agent 365 per testare in applicazioni Microsoft 365 come Teams, Word e Outlook.

Prerequisiti

Prima di iniziare il test dell'agente, verifica di avere i prerequisiti seguenti installati:

Prerequisiti comuni

• Editor di codice: qualsiasi editor di codice di tua scelta. Visual Studio Code è consigliato.
• Agents Playground: Installa Agents Playground utilizzando uno dei seguenti metodi:
  • Finestre: winget install agentsplayground
  • NPM: npm install -g @microsoft/m365agentsplayground
• Interfaccia della riga di comando di A365: obbligatoria per la distribuzione e la gestione degli agenti. Installa la CLI dell'Agent 365.
• Accesso all'API LLM: scegli il servizio appropriato in base alla configurazione dell'agente o al provider di modelli preferito:
  • Chiave API OpenAI: Ottieni la tua chiave API OpenAI.
  • Azure OpenAI: Crea e distribuisci una risorsa Azure OpenAI per ottenere la chiave API e il endpoint.
• Configurazione del Portale Sviluppatori: Dopo aver pubblicato il tuo agente, devi configurare il blueprint dell'agente nel Portale Sviluppatori prima di creare le istanze. Impara a configurare il progetto dell'agente nel Portale Sviluppatori

Prerequisiti specifici della lingua

Configura l'ambiente di test dell'agente

Questa sezione descrive come impostare le variabili dell'ambiente, autenticare l'ambiente di sviluppo e preparare il tuo agente alimentato da Agent 365 per i test.

La configurazione dell'ambiente di test dell'agente segue un flusso di lavoro sequenziale:

1. Configura il tuo ambiente - Crea o aggiorna il file di configurazione dell'ambiente.

2. Configurazione LLM - Ottieni le chiavi API e configura le impostazioni di OpenAI o Azure OpenAI.

3. Configura l'autenticazione - Imposta l'autenticazione agentica.

4. Informazioni di riferimento sulle variabili di ambiente: configura le variabili di ambiente obbligatorie:

   1. Variabili di autenticazione
   2. Configurazione dell'endpoint MCP
   3. Variabili di osservabilità
   4. Configurazione del server dell'applicazione Agent

Dopo aver completato questi passaggi, è possibile iniziare a testare l'agente nel playground per gli agenti.

Passaggio 1: Configurare l'ambiente

Imposta il file di configurazione:

cp .env.template .env

cp .env.template .env

Passaggio 2: configurazione LLM

Configura le impostazioni OpenAI o Azure OpenAI per i test locali. Aggiungi le tue chiavi API e gli endpoint dei servizi dai prerequisiti al tuo file di configurazione insieme a eventuali parametri del modello.

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

{
  "AIServices": {
    "AzureOpenAI": {
      "DeploymentName": "", // Deployment (as opposed to model) name of the Azure OpenAI model
      "Endpoint": "", // Endpoint of the Azure OpenAI model deployment
      "ApiKey": "" // API Key of the Azure OpenAI model deployment
    },
    "OpenAI": {
      "ModelId": "", // Model ID of the OpenAI model
      "ApiKey": "" // API Key of the OpenAI model
    },
    "UseAzureOpenAI": true // Flag to use Azure OpenAI vs OpenAI
  }
}

Passo 3: Configura l'autenticazione per il tuo agente

Scegli uno dei seguenti metodi di autenticazione per il tuo agente:

• Autenticazione agentica - Da utilizzare per scenari di produzione o quando è disponibile un utente agente.
• Autenticazione del token portatore - Utilizzare solo per scenari iniziali di sviluppo e test prima che gli utenti agenti siano disponibili.

Autenticazione agentica

Usa il comando CLI a365 config display Agent 365 per recuperare le credenziali del tuo progetto agente.

a365 config display -g

Questo comando visualizza la configurazione del progetto dell'agente. Copia i valori seguenti:

Utilizza questi valori per configurare l'autenticazione agentica nell'agente:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>

USE_AGENTIC_AUTH=true
connections__service_connection__settings__clientId=<agentBlueprintId>
connections__service_connection__settings__clientSecret=<agentBlueprintClientSecret>
connections__service_connection__settings__tenantId=<your-tenant-id>

{
  "AgentBluePrint": {
    "Settings": {
      "ClientId": "<agentBlueprintId>",
      "ClientSecret": "<agentBlueprintClientSecret>",
      "TenantId": "<your-tenant-id>"
    }
  }
}

Autenticazione del token di connessione

Per scenari iniziali di sviluppo e test in cui gli utenti dell'agente non sono disponibili, usa l'autenticazione con bearer token per testare il tuo agente. Questo metodo utilizza l'autenticazione interattiva del browser per ottenere un token di accesso delegato, che permette al tuo agente di chiamare gli strumenti MCP Server con i permessi utente. Questo approccio simula come un utente agente accede alle risorse in produzione senza richiedere un'istanza effettiva dell'agente.

Per prima cosa, usa a365 develop add-permissions per aggiungere i permessi necessari al server MCP alla tua applicazione:

a365 develop add-permissions

Poi, usare a365 develop get-token per recuperare e configurare i gettoni portatori:

a365 develop get-token

Il get-token comando automaticamente:

• Recupera i token portatori per tutti i server MCP configurati nel tuo ToolingManifest.json file
• Aggiorna i file di configurazione del progetto con la BEARER_TOKEN variabile ambiente

Passaggio 4: informazioni di riferimento sulle variabili di ambiente

Completa la configurazione dell'ambiente configurando le seguenti variabili di ambiente obbligatorie:

• Variabili di autenticazione: impostazioni obbligatorie per l'autenticazione agentica
• Configurazione dell'endpoint MCP: specifica l'endpoint della piattaforma Agent 365
• Variabili di osservabilità: abilita la registrazione e la traccia distribuita
• Configurazione del server dell'applicazione Agent: configura la porta in cui viene eseguito il server dell'agente

Variabili di autenticazione

Configura le impostazioni del gestore di autenticazione necessarie per il corretto funzionamento dell'autenticazione agentica.

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION

# Agentic Authentication Options
agentic_type=agentic
agentic_altBlueprintConnectionName=service_connection
agentic_scopes=ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/.default

# Set service connection as default
connectionsMap__0__serviceUrl=*
connectionsMap__0__connection=service_connection

{
  "AgentApplication": {
    "StartTypingTimer": false,
    "RemoveRecipientMention": false,
    "NormalizeMentions": false,
    "UserAuthorization": {
      "AutoSignin": false,
      "Handlers": {
        "agentic": {
          "Type": "AgenticUserAuthorization",
          "Settings": {
            "Scopes": [
              "https://graph.microsoft.com/.default"
            ]
          }
        }
      }
    }
  },
  "ConnectionsMap": [
    {
      "ServiceUrl": "*",
      "Connection": "ServiceConnection"
    }
  ]
}

Configurazione dell'endpoint MCP

La configurazione dell'endpoint MCP (Model Context Protocol) è obbligatoria per specificare l'endpoint della piattaforma Agent 365 a cui deve connettersi l'agente. Quando generi il manifesto degli strumenti che definisce i server degli strumenti per il tuo agente, devi specificare l'endpoint della piattaforma MCP. Questo endpoint determina l'ambiente (preproduzione, test o produzione) a cui si connettono i server degli strumenti MCP per le funzionalità di integrazione di Microsoft 365.

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>

{
  "profiles": {
    "Sample Agent": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "MCP_PLATFORM_ENDPOINT": "<MCP endpoint>"
      },
      "applicationUrl": "https://localhost:64896;http://localhost:64897"
    }
  }
}

Variabili di osservabilità

Configura queste variabili obbligatorie per abilitare la registrazione e la traccia distribuita per l'agente. Scopri di più sulle caratteristiche di osservabilità e sulle migliori pratiche.

Configurazione del server dell'applicazione Agent

Configura la porta in cui viene eseguito il server dell'applicazione dell'agente. Questa impostazione è opzionale e si applica agli agenti Python e JavaScript.

# Server Configuration
PORT=3978

# Server Configuration
PORT=3978

Installare le dipendenze e avviare il server dell'applicazione dell'agente

Dopo aver configurato l'ambiente, installa le dipendenze richieste e avvia localmente il server applicativo dell'agente per i test.

Installare le dipendenze

uv pip install -e .

python <main.py>

uv run python <main.py>

npm install

npm run dev

dotnet restore

dotnet build

dotnet run --launch-profile "Sample Agent with MCP Platform"

Il tuo server agente è ora in esecuzione e pronto a ricevere richieste da Agents Playground o applicazioni Microsoft 365.

Testare l'agente nel playground per gli agenti

Il playground per agenti è uno strumento di test locale che simula l'ambiente Microsoft 365 senza richiedere una configurazione completa del tenant. È il modo più rapido per convalidare la logica e le chiamate degli strumenti dell'agente. Per altre informazioni, vedi Eseguire test con il playground per gli agenti.

Apri un nuovo terminale (PowerShell su Windows) e avvia il playground per gli agenti:

agentsplayground

Questo comando apre un browser web con l'interfaccia Agents Playground. Lo strumento visualizza un'interfaccia di chat in cui puoi inviare messaggi all'agente.

Test di base

Per iniziare, verifica che l'agente sia configurato correttamente. Invia un messaggio all'agente:

What can you do?

L'agente risponde con le istruzioni con cui è configurato, in base al prompt di sistema e alle capacità del tuo agente. Questa risposta conferma che:

• L'agente è in esecuzione correttamente
• L'agente può elaborare messaggi e rispondere
• La comunicazione tra il playground per gli agenti e l'agente funziona

Chiamate allo strumento di test

Dopo aver configurato i tuoi server di strumenti MCP in toolingManifest.json (vedi Tooling per istruzioni di configurazione), le invocazioni degli strumenti di test con esempi come questi:

Prima di tutto, verifica quali strumenti sono disponibili:

List all tools I have access to

Poi, testa le invocazioni specifiche degli strumenti:

Strumenti di posta elettronica

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

Risposta attesa: L'agente invia un'email utilizzando il server Mail MCP e conferma che il messaggio è stato inviato.

Strumenti del calendario

List my calendar events for today

Risposta attesa: L'agente recupera e mostra gli eventi del calendario per il giorno corrente.

Strumenti di SharePoint

List all SharePoint sites I have access to

Risposta attesa: L'agente interroga SharePoint e restituisce una lista dei siti a cui hai accesso.

È possibile visualizzare le chiamate dello strumento in:

• Finestra della chat: vedi la risposta dell'agente e tutte le chiamate agli strumenti
• Pannello dei log: vedi informazioni dettagliate sulle attività, inclusi i parametri e le risposte degli strumenti

Testare con le attività di notifica

Durante lo sviluppo locale, testa gli scenari di notifica simulando attività personalizzate in Agents Playground. Questa simulazione ti aiuta a verificare la gestione delle notifiche da parte del tuo agente prima di distribuirlo in produzione.

Prima di testare le attività di notifica, assicurati di:

• Configura i server degli strumenti MCP necessari nel tuo toolingManifest.jsonfile . Altre informazioni sugli strumenti
• Abilita le notifiche per il tuo agente. Impara come configurare le notifiche

Le notifiche richiedono il corretto funzionamento della configurazione dello strumento e della configurazione delle notifiche. Puoi testare scenari come notifiche via email o commenti Word utilizzando la funzione attività personalizzata.

Per inviare attività personalizzate:

1. Avvia il tuo agente e il tuo parco giochi degli agenti.
2. In Agents Playground, vai su Simulazione di un'attività>personalizzata.
3. Copia quello conversationId dall'attività. (L'ID della conversazione cambia ogni volta che Agents Playground riavvia.)
4. Incolla il codice JSON dell'attività personalizzata e aggiorna il campo personal-chat-id con l'ID conversazione copiato. Fai riferimento all'esempio della notifica via email.
5. Seleziona Invia attività.
6. Visualizza il risultato sia nella chat che nel pannello log.

Notifica e-mail

Questa configurazione simula un'email inviata all'agente. Sostituisci i valori segnaposto con i dettagli effettivi dell'agente:

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

Visualizza i log di osservabilità

Per visualizzare i log di osservabilità durante lo sviluppo locale, fornisci all'agente il codice osservabilità (vedi Osservabilità per gli esempi di codice) e configura le variabili di ambiente come descritto in Variabili di osservabilità. Dopo la configurazione, le tracce in tempo reale vengono visualizzate nella console che mostra:

• Tracce di chiamata dell'agente
• Dettagli di esecuzione dello strumento
• Chiamate di inferenza LLM
• Messaggi di input e output
• Utilizzo dei token
• Tempi di risposta
• Informazioni sugli errori

Questi log ti aiutano a debugare i problemi, comprendere il comportamento degli agenti e ottimizzare le prestazioni.

Passaggi successivi

Dopo aver testato con successo il tuo agente localmente, sei pronto a distribuirlo su Azure e pubblicarlo su Microsoft 365.

Segui il ciclo di sviluppo di Agent 365 per testare in applicazioni Microsoft 365 come Teams, Word e Outlook.

Risoluzione dei problemi

Questa sezione fornisce soluzioni ai problemi comuni che potresti incontrare quando testi il tuo agente localmente.

Problemi relativi a connessioni e ambienti

Questi problemi sono correlati a connettività di rete, conflitti di porte e problemi di configurazione dell'ambiente che possono impedire all'agente di comunicare correttamente.

Problemi di connessione del playground per gli agenti

Sintomo: Agents Playground non riesce a connettersi con il tuo agente.

Soluzioni:

• Verifica che il server agente sia in funzione.
• Controlla che i numeri di porting corrispondano tra il tuo agente e Agents Playground.
• Assicurati che non ci siano regole firewall che bloccano le connessioni locali.
• Prova a riavviare sia l'agente che quello dell'agente.

Versione obsoleta del playground per gli agenti

Sintomo: Errori imprevisti o funzionalità mancanti in Agents Playground.

Soluzione: Disinstalla e reinstalla Agents Playground.

winget uninstall agentsplayground
winget install agentsplayground

Conflitti di porte

Sintomo: La porta di errore indica è già in uso.

Soluzione:

• Ferma qualsiasi altra situazione del tuo agente.
• Cambia la porta nella tua configurazione.
• Uccidi qualsiasi processo che usa la porta.

# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Non è possibile aggiungere DeveloperMCPServer

Sintomo: Errore nel tentativo di aggiungere DeveloperMCPServer in VS Code.

Soluzione: chiudi e riapri Visual Studio Code, quindi prova ad aggiungere nuovamente il server.

Problemi di autenticazione e token

Questi problemi si verificano quando il tuo agente non riesce ad autenticarsi correttamente con i servizi Microsoft 365 o quando le credenziali scadono o vengono configurate male.

Sintomi:

• 401 Errori non autorizzati
• Messaggi "Token portatore scaduto"
• Fallimenti dell'autenticazione agentica

Causa radice:

• I token scadono dopo circa un'ora
• Configurazione di autenticazione errata
• Credenziali mancanti o non valide

Soluzioni:

• Per la scadenza del token portatore

  Aggiorna il token e aggiorna le variabili ambientali.

  # Get a new token
  a365 develop get-token
  
  # Update your .env file with the new token
  

• Per errori di autenticazione agentica (Python)

  Controlla il tuo .env fascicolo:

  # Should be (with underscore):
  AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION
  
  # Not:
  AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection
  

• Per le credenziali mancanti

  Conferma che le credenziali richieste siano presenti prima del test.

  Assicurare .env o appsettings.json contenere:

  • Chiavi API e segreti
  • ID del locatario
  • ID cliente
  • ID blueprint (se si utilizza l'autenticazione agentica)

  Verifica:

  Prova con una semplice richiesta in Agents Playground. Dovresti ricevere una risposta senza errori 401

• Problemi con gli strumenti e le notifiche

  Questi problemi riguardano le invocazioni degli strumenti, le interazioni con i server MCP e la consegna delle notifiche.

Messaggio e-mail non ricevuto

Sintomo: l'agente indica che è stato inviato un messaggio e-mail, ma non lo si riceve

Soluzioni:

• Controlla la cartella Spam/Spam.
• La consegna delle email può essere ritardata di qualche minuto - aspetta fino a cinque minuti.
• Verifica che l'indirizzo email del destinatario sia corretto.
• Controlla i log degli agenti per eventuali errori durante l'invio delle email.

Risposte ai commenti di Word non funzionanti

Problema noto: il servizio di notifiche attualmente non può rispondere direttamente ai commenti Word. Questa funzionalità è in fase di sviluppo.

Messaggi che non raggiungono l'agente

Sintomo: I messaggi inviati all'agente in Teams non vengono ricevuti dalla tua candidatura.

Possibili cause:

• Blueprint dell'agente non configurato nel Portale Sviluppatori.
• Problemi con Azure Web App (fallimenti di implementazione, app non in esecuzione, errori di configurazione).
• Istanza dell'agente non creata correttamente in Teams.

Soluzioni:

• Verifica configurazione del Portale Sviluppatori:

  Assicurati di completare la configurazione del blueprint dell'agente nel Portale Sviluppatori. Impara a configurare il blueprint dell'agente nel Portale Sviluppatori.

• Controlla la salute di Azure Web App:

  Se distribuisci il tuo agente su Azure, verifica che l'app Web funzioni correttamente:

  1. Accedere al portale di Azure.
  2. Vai alla tua risorsa Web App.
  3. Controllalo statodella panoramica> (dovrebbe mostrare "In corso").
  4. Controlla il flusso di log sotto Monitoraggio per errori di runtime.
  5. Rivedi i log del Centro di Distribuzione per verificare che il deployment sia riuscito.
  6. Verifica Configurazione>Le impostazioni dell'applicazione contengono tutte le variabili di ambiente richieste.

• Verifica la creazione dell'istanza dell'agente:

  Assicurati di creare correttamente l'istanza dell'agente in Microsoft Teams:

  1. Apri Microsoft Teams.
  2. Vai su Apps e cerca il tuo agente.
  3. Verifica che l'agente appaia nei risultati di ricerca.
  4. Se non è stato trovato, verifica che sia pubblicato nel centro amministrazione Microsoft 365 - Agenti.
  5. Crea una nuova istanza selezionando Aggiungi il tuo agente.
  6. Per istruzioni dettagliate, vedi Agenti a bordo.