Guida introduttiva: Configurare ed eseguire l'agente di esempio del framework di Python Agent

In questa guida introduttiva, ti accompagniamo nella configurazione di un agente del framework Python funzionante, utilizzando Agent 365 per strumenti, notifiche, osservabilità, e per testare l'agente tramite Agents Playground e Teams.

Prerequisites

  • Se si prevede di usare Visual Studio Code, è necessario aver installato .NET. È consigliabile .NET 8.0.

  • Python 3.11+ installato

  • Gestore di pacchetti UV installato. Installalo in un terminale usando pip install uv.

  • Dipendenze del Toolkit Agent di Microsoft / Framework degli Agenti

    L'esempio usato nella procedura dettagliata si basa sulle librerie di Agent Framework fornite tramite Microsoft 365 Agents Toolkit o ATK. Queste verranno installate automaticamente quando si usa l'estensione Agents Toolkit in VS Code per scaffoldare l'esempio, oppure puoi installare il pacchetto manualmente usando questo comando:

    uv pip install -e . --prerelease=allow

  • Accesso a GitHub

  • Un progetto di agente IA esistente. Questa guida introduttiva usa un agente di esempio di Agent 365 da Microsoft 365 agent toolkit noto anche come ATK in VS Code.

  • CLI di A365

  • Autenticazione dell'identità dell'agente

Configurare il framework agent e l'esempio di Python da Microsoft 365 Agents Toolkit

Per preparare tutto, installi Microsoft 365 Agents Toolkit in VS Code, apri la galleria di esempi e esegui il scaffolding del framework Agent e del campione di Python in locale, così potrai configurarlo e eseguirlo successivamente. Gli screenshot seguenti mostrano ciò che ci si aspetta di vedere mentre si procede.

  1. Aprire Visual Studio Code, aprire quindi il pannello ExtensionsCtrl+Shift+X.

  2. Nella barra di ricerca digita "Agents Toolkit".
    Verrà visualizzato il risultato visualizzato nello screenshot seguente:

    Screenshot della ricerca nel Marketplace delle Estensioni per Agents Toolkit.

  3. Selezionare Microsoft 365 Agents Toolkit.

  4. Seleziona Installa.

    VS Code mostra la visualizzazione dei dettagli dell'estensione simile a:

    Screenshot della pagina Dettagli estensione con i pulsanti Installa e Abilita.

  5. Dopo l'installazione, l'icona Toolkit degli Agenti M365 viene visualizzata nella barra di navigazione a sinistra.

  6. Selezionala per aprire l'esperienza di benvenuto.

    Verranno ora visualizzate opzioni come Crea un agente dichiarativo, Creare un nuovo agente o app e Visualizza esempi, come illustrato di seguito:

    Screenshot della visualizzazione iniziale del toolkit con le opzioni Crea un agente dichiarativo, Crea un nuovo agente o app e Visualizza esempi.

  7. Seleziona Visualizza esempi.

  8. Nell'elenco degli esempi, scorrere per trovare l'esempio dell'agente Agent framework + Python.

  9. Seleziona.

    Verranno visualizzate due opzioni: Create (scaffold localmente) o View in GitHub.

  10. Scegliere Create.

    Screenshot di Agent Framework Agent con Agent 365 SDK, esempio di utilizzo di Python.

  11. Quando richiesto, seleziona una cartella nel computer in cui deve essere generato l'esempio. Ad esempio: C:\A365-python-sample

    Il toolkit crea la struttura del framework Agent e un esempio di Python in una sottocartella (ad esempio sample_agent) che si apre in automatico in Visual Studio Code.

    Al termine dello scaffolding, ora hai un framework agente completamente funzionante + progetto agente in Python sul tuo computer.

  12. Installare i pacchetti Agent 365 necessari

    Prima di eseguire l'esempio, apri pyproject.toml nel tuo progetto e verifica che tutte le dipendenze necessarie di Agent 365 e del framework Agent siano elencate. L'esempio generato da Microsoft 365 Agents Toolkit include già queste voci.

    Una volta che hai esaminato pyproject.toml, installa tutto eseguendo questo comando:

    uv pip install -e . --prerelease=allow

    In questo modo vengono estratte tutte le raccolte SDK di Agent 365, le dipendenze del framework di Agent, i componenti di hosting e tutte le altre dipendenze definite nell'esempio.

  13. Dopo l'installazione, verifica che il progetto venga compilato ed eseguito avviando il server di sviluppo usando questo comando:

    uv run python start_with_generic_host.py

Aggiungere Microsoft 365 strumenti (server MCP)

Puoi esplorare e gestire i server MCP usando i comandi di sviluppo a365 nell'interfaccia della riga di comando.

Quando lavori con gli strumenti Microsoft MCP, puoi:

  • Individuare i server MCP disponibili per l'uso
  • Aggiungi uno o più server MCP alla configurazione dell'agente
  • Esamina i server MCP attualmente configurati
  • Rimuovi i server MCP non più necessari

Dopo l'aggiunta dei server MCP, il manifesto degli strumenti dell'agente si espande per includere voci simili a:

{
   "mcpServers": [
      {
         "mcpServerName": "mcp_MailTools",
         "mcpServerUniqueName": "mcp_MailTools",
         "scope": "McpServers.Mail.All",
         "audience": "api://00001111-aaaa-2222-bbbb-3333cccc4444"
      }
   ]
}

Informazioni su come aggiungere e gestire gli strumenti

Gestione e sottoscrizione delle notifiche

L'agente di esempio sottoscrive tutte le notifiche SDK di Agent 365 usando onAgentNotification("*") e le instrada a un singolo gestore. Questo gestore consente all'agente di reagire agli eventi in background o di sistema, non solo ai messaggi utente diretti.

Informazioni su come inviare notifiche agli agenti

Nel codice seguente viene illustrato come viene configurata la notifica nel file agent.py.

if notification_type == NotificationTypes.EMAIL_NOTIFICATION: 
if not hasattr(notification_activity, "email") or not notification_activity.email: return "I could not find the email notification details."
email = notification_activity.email
email_body = getattr(email, "html_body", "") or getattr(email, "body", "")

message = (
    "You have received the following email. "
    "Please follow any instructions in it. "
    f"{email_body}"
)

result = await self.agent.run(message)
return self._extract_result(result) or "Email notification processed."

Observability

Importante

Questo campione utilizza l'SDK di osservabilità Agent 365 obsoleto. Non usare questo pattern per una nuova integrazione di osservabilità. Usa invece la distribuzione Microsoft OpenTelemetry.

Il seguente estratto mostra la configurazione obsoleta dell'SDK di osservabilità dell'Agente 365 usata dal campione.

Il codice seguente illustra un esempio di osservabilità semplificata nel file agent.py.

def _enable_agentframework_instrumentation(self): 
"""Enable Agent Framework instrumentation.""" 
try: 
AgentFrameworkInstrumentor().instrument() 
logger.info("✅ Instrumentation enabled")
 except Exception as e: 
logger.warning(f"⚠️ Instrumentation failed: {e}")

Questo codice utilizza la configurazione obsoleta dell'SDK Agent 365 Observability richiesta per l'esempio Python + Agent Framework. Per la configurazione completa e le indicazioni sulla migrazione di Microsoft OpenTelemetry, consulta la documentazione SDK obsoleta.

Testa il tuo agente

Imposta le variabili di ambiente necessarie, seleziona una modalità di autenticazione e avvia l'agente in locale. È possibile testare tutti gli elementi end-to-end con Agents Playground senza che sia necessario un tenant Microsoft 365, a meno che non si voglia pubblicare l'agente e usarlo in app come Teams o Outlook.

Panoramica dei passaggi di test

  • Aggiungi le chiavi API e le impostazioni del modello a un file .env in modo che l'esempio possa comunicare con un LLM.
  • Scegli la modalità di autenticazione. Per lo sviluppo locale, l'esempio supporta l'Agentic Auth utilizzando i valori creati dal Blueprint dell'Agente.
  • Avvia l'agente in locale, che lo espone a strumenti come Agents Playground.
  • Usa Playground per gli agenti per testare messaggi, strumenti e notifiche senza configurare un tenant o distribuirlo.
  • Quando si è pronti per il comportamento nel mondo reale, pubblicate un tenant Microsoft 365 e testate l'agente all'interno di Teams, Outlook o altre applicazioni Microsoft 365.

Altre informazioni sui test

Pubblicare l'agente

Quando l'agente è pronto per esperienze di Microsoft 365 effettive, ad esempio chat di Teams, messaggi Outlook, Word @mentions, lo si pubblica in un tenant Microsoft 365. Il comando CLI publish Agent 365 gestisce il packaging: aggiorna il tuo manifesto, raggruppa tutto e carica l'agente nel centro amministrativo Microsoft.

Durante la pubblicazione, esamina e personalizza il nome, la descrizione, le icone e la versione dell'agente prima di completare il caricamento. Una volta pubblicato, il tuo agente diventa registrato e installabile all'interno del tenant.

Importante

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

Puoi visualizzare gli agenti pubblicati qui: https://admin.cloud.microsoft/#/agents/all

Altre informazioni sul flusso di lavoro completo e istruzioni dettagliate

  • Ultimo aggiornamento: