Condividi tramite

Testare gli agenti con l'SDK Microsoft Agent 365

Importante

Devi far parte del programma di anteprima Frontier per ottenere l'accesso in anteprima a Microsoft Agent 365. Frontier ti mette in contatto diretto con le ultime innovazioni di Microsoft nell'IA. Le anteprime Frontier sono soggette alle condizioni di anteprima esistenti dei tuoi contratti del cliente. Poiché queste funzionalità sono ancora in fase di sviluppo, la disponibilità e le funzionalità possono cambiare nel tempo.

Testa l'agente localmente tramite il playground per agenti prima della distribuzione. Questa guida illustra la configurazione dell'ambiente di sviluppo, la configurazione dell'autenticazione e la convalida delle funzionalità dell'agente con lo strumento playground per agenti per i test.

Quando l'agente funziona in locale, è possibile distribuirlo e pubblicarlo per il test in applicazioni di Microsoft 365 come Teams.

Prerequisiti

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

Prerequisiti comuni

Prerequisiti specifici della lingua

Configura l'ambiente di test dell'agente

Questa sezione illustra l'impostazione delle variabili di ambiente, l'autenticazione dell'ambiente di sviluppo e la preparazione dell'agente con tecnologia Agent 365 per i test.

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

  1. Configura l'ambiente: crea o aggiorna il file di configurazione dell'ambiente

  2. Configurazione LLM: recupera le chiavi API e configura le impostazioni OpenAI o Azure OpenAI

  3. Configura l'autenticazione: configura l'autenticazione dell'agente

  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

Nota

Fai riferimento agli esempi dell'SDK Microsoft Agent 365 per trovare i modelli di configurazione che mostrano i campi obbligatori.

Passaggio 2: configurazione LLM

Configura le impostazioni OpenAI o Azure OpenAI per i test locali. Aggiungi le chiavi API e gli endpoint di servizio ottenuti dai prerequisiti al file di configurazione insieme a tutti i parametri del modello.

Aggiungi il tuo file .env:

# 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=

Variabili di ambiente LLM Python

Variabile Descrizione Obbligatorio Esempio
OPENAI_API_KEY Chiave API per il servizio OpenAI Per OpenAI sk-proj-...
AZURE_OPENAI_API_KEY Chiave API per Servizio OpenAI di Azure Per Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT URL endpoint di Servizio OpenAI di Azure Per Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Nome della distribuzione in Azure OpenAI Per Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION Versione dell'API per Azure OpenAI Per Azure OpenAI 2024-02-15-preview

Passo 3: Configura l'autenticazione per il tuo agente

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

Autenticazione agentica

Utilizza il comando a365 config display dell'interfaccia della riga di comando di A365 per recuperare le credenziali del progetto dell'agente.

a365 config display -g

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

Valore Descrizione
agentBlueprintId ID client dell'agente
agentBlueprintClientSecret Segreto client dell'agente
tenantId ID tenant di Microsoft Entra

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

Aggiungi le impostazioni seguenti al file .env, sostituendo i valori segnaposto con le credenziali effettive:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Variabile Descrizione Obbligatorio Esempio
USE_AGENTIC_AUTH Abilitare la modalità di autenticazione agentica Sì true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID ID client del progetto dell'agente da a365 config display -g Sì 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Segreto client del progetto dell'agente da a365 config display -g Sì abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID ID tenant Microsoft Entra da a365 config display -g Sì adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

Autenticazione del token di connessione

Per scenari iniziali di sviluppo e test in cui gli utenti degli agenti non sono disponibili, puoi usare l'autenticazione con token portatore per testare il tuo 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

Nota

I gettoni portatori scadono dopo circa 1 ora. Usalo a365 develop get-token per aggiornare i token scaduti.

Passaggio 4: informazioni di riferimento sulle variabili di ambiente

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

Variabili di autenticazione

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

Aggiungi il tuo file .env:

# 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
Variabile Descrizione Obbligatorio
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Tipo di gestore di autenticazione Sì
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Ambiti di autenticazione per Microsoft Graph Sì
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Nome di connessione del progetto alternativo Sì
CONNECTIONSMAP_0_SERVICEURL Modello di URL del servizio per il mapping delle connessioni Sì
CONNECTIONSMAP_0_CONNECTION Nome della connessione per il mapping Sì

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.

Aggiungi il tuo file .env:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Variabile Descrizione Obbligatorio Default Esempio
MCP_PLATFORM_ENDPOINT URL dell'endpoint della piattaforma MCP (preprod, test o prod) No Endpoint di produzione

Importante: se MCP_PLATFORM_ENDPOINT non viene specificato, per impostazione predefinita viene impostato l'endpoint di produzione.

Variabili di osservabilità

Configura queste variabili obbligatorie per abilitare la registrazione e la traccia distribuita per l'agente. Altre informazioni sulle funzionalità di osservabilità e sulle procedure consigliate

Nota

La configurazione dell'osservabilità è la stessa in tutte le lingue.

Variabile Descrizione Default Esempio
ENABLE_A365_OBSERVABILITY Abilitare/disabilitare l'osservabilità false true
ENABLE_A365_OBSERVABILITY_EXPORTER Esportare tracce nel servizio di osservabilità false true
OBSERVABILITY_SERVICE_NAME Nome del servizio per la traccia Nome agente my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Spazio dei nomi del servizio agent365-samples my-company-agents

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.

Aggiungi il tuo file .env:

# Server Configuration
PORT=3978
Variabile Descrizione Obbligatorio Default Esempio
PORT Numero di porta su cui viene eseguito il server dell'agente No 3978 3978

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

Dopo aver configurato l'ambiente, è necessario installare le dipendenze obbligatorie e avviare il server applicazioni dell'agente in locale per il test.

Installare le dipendenze

uv pip install -e .

Questo comando legge le dipendenze del pacchetto definite in pyproject.toml e le installa da PyPI. Quando si crea un'applicazione agente da zero, è necessario creare un file pyproject.toml per definire le dipendenze. Gli agenti di esempio del repository di esempi hanno già questi pacchetti definiti. Puoi aggiungerli o aggiornarli in base alle esigenze.

Avviare il server applicazioni dell'agente

python <main.py>

Sostituisci <main.py> con il nome del file Python principale che contiene il punto di ingresso per l'applicazione dell'agente (ad esempio, start_with_generic_host.py, app.py o main.py).

Oppure utilizzando UV:

uv run python <main.py>

Il server dell'agente dovrebbe ora essere in esecuzione e pronto per ricevere richieste dalle applicazioni del playground per agenti o 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.

Nota

Quando usi l'autenticazione agentica, la messaggistica diretta in Agents Playground attualmente non è supportata. Devi invece fare test tramite attività personalizzate. Vedi Attività Test con notifiche per i dettagli.

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 server degli strumenti MCP in toolingManifest.json (vedi Strumenti per istruzioni di installazione), le chiamate dello strumento di test con esempi simili ai seguenti:

Prima di tutto, verifica quali strumenti sono disponibili:

List all tools I have access to

Testa quindi chiamate di strumenti specifiche:

Strumenti di posta elettronica

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

Risposta prevista: l'agente invia un messaggio e-mail usando il server McP mail 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 prevista: l'agente esegue una query su SharePoint e restituisce un elenco di siti a cui si ha 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, è possibile testare gli scenari di notifica simulando attività personalizzate nel playground per gli agenti. Questa simulazione ti permette di verificare la gestione delle notifiche da parte del tuo agente prima di distribuirlo in produzione.

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

Le notifiche richiedono il corretto funzionamento della configurazione dello strumento e della configurazione delle notifiche. È possibile testare scenari come le notifiche tramite e-mail o i commenti di Word usando la funzionalità di attività personalizzata.

Per inviare attività personalizzate:

  1. Avviare l'agente e il playground per gli agenti
  2. Nel playground per gli agenti, passa a Simula un'attività>Attività personalizzata
  3. Copia conversationId dall'attività (l'ID conversazione cambia ogni volta che il playground per gli agenti viene riavviato)
  4. Incolla il codice JSON dell'attività personalizzata e aggiorna il campo personal-chat-id con l'ID conversazione copiato. Fai riferimento all'esempio di notifica tramite e-mail
  5. Seleziona Invia attività
  6. Visualizza il risultato sia nella conversazione di chat che nel pannello di 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 consentono di eseguire il debug dei problemi, comprendere il comportamento dell'agente e ottimizzare le prestazioni.

Risoluzione dei problemi

Questa sezione fornisce soluzioni ai problemi comuni che possono verificarsi durante il test dell'agente in locale.

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: il playground per gli agenti non riesce a connettersi all'agente

Soluzioni:

  • Verificare che il server agente sia in esecuzione
  • Verificare che i numeri di porta corrispondano tra l'agente e il playground per gli agenti
  • Verificare che non vi siano regole del firewall che bloccano le connessioni locali
  • Provare a riavviare sia l'agente che il playground per gli agenti

Versione obsoleta del playground per gli agenti

Sintomo: errori imprevisti o funzionalità mancanti nel playground per gli agenti

Soluzione: disinstalla e reinstalla il playground per gli agenti:

winget uninstall agentsplayground
winget install agentsplayground

Conflitti di porte

Sintomo: errore che indica che la porta è già in uso

Soluzione:

  • Arrestare qualsiasi altra istanza dell'agente
  • Modificare la porta nella configurazione
  • Termina tutti i processi usando la porta:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Non è possibile aggiungere DeveloperMCPServer

Sintomo: errore durante il tentativo di aggiungere DeveloperMCPServer in VS Code

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

Problemi di autenticazione

Questi problemi si verificano quando l'agente non riesce a eseguire correttamente l'autenticazione con i servizi di Microsoft 365 o quando le credenziali sono scadute o configurate in modo errato.

Token di connessione scaduto

Sintomo: errori di autenticazione o 401 risposte non autorizzate

Soluzione: i token di connessione scadono dopo circa 1 ora. Acquisisci un nuovo token e aggiorna la configurazione.

Errori di autenticazione dell'agente in Python

Sintomo: errore durante l'acquisizione del token dell'istanza dell'agente

Soluzione: verifica l'impostazione ALT_BLUEPRINT_NAME in .env:

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

Problemi relativi agli strumenti e alle notifiche

Questi problemi comportano problemi con le chiamate agli strumenti, le interazioni del server MCP e il recapito delle notifiche.

Messaggio e-mail non ricevuto

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

Soluzioni:

  • Controllare la cartella di posta indesiderata
  • Il recapito dei messaggi e-mail può essere ritardato di alcuni minuti: attendi fino a 5 minuti
  • Verificare che l'indirizzo e-mail del destinatario sia corretto
  • Controllare i log dell'agente per eventuali errori durante l'invio di messaggi e-mail

Risposte ai commenti di Word non funzionanti

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

Messaggi che non raggiungono l'agente

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

Possibili cause:

  • Agent blueprint 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:

  1. Verifica configurazione del Portale Sviluppatori:

    Assicurati di aver completato la configurazione del blueprint dell'agente nel Portale Sviluppatori. Consulta Configura il progetto dell'agente nel Portale Sviluppatori per passaggi dettagliati.

  2. Controlla la salute di Azure Web App:

    Se il tuo agente è distribuito su Azure, verifica che l'App Web stia funzionando correttamente:

    1. Navigate to Azure Portal
    2. Vai alla tua risorsa Web App
    3. Controllalo stato> (dovrebbe mostrare "In corso")
    4. Controlla il flusso di log sotto Monitoraggio per errori di esecuzione
    5. Esamina 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

  3. Verifica la creazione dell'istanza dell'agente:

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

    1. Open Microsoft Teams
    2. Vai su App e cerca il tuo agente
    3. Verifica che l'agente compare nei risultati di ricerca
    4. Se non viene trovato, verifica che sia pubblicato nel Microsoft 365 Admin Center - Agents
    5. Crea una nuova istanza selezionando Aggiungi al tuo agente
    6. Per istruzioni dettagliate, vedi Agenti a bordo

Visualizzazione delle informazioni della Guida

Se si verificano problemi non trattati in questa sezione di risoluzione dei problemi, esplora queste risorse:

Repository dell'SDK di Microsoft Agent 365

Altro supporto

Passaggi successivi

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

  • Distribuisci e pubblica agenti: Impara come distribuire il tuo agente su Azure Web App e pubblicarlo su Microsoft Admin Center, rendendolo disponibile per la tua organizzazione per scoprire e creare istanze di agente in Microsoft 365.
  • Last updated on