Condividi tramite

Guida introduttiva: configurare ed eseguire l'agente di esempio di Agent Framework di Python

In questa Guida introduttiva viene illustrata la configurazione di un agente Agent framework di Python funzionante usando strumenti Agent 365, notifiche, osservabilità e test dell'agente con Agents Playground e Teams.

Prerequisiti

  • Se prevedi di usare Visual Studio Code, è necessario che .NET sia installato. .NET 8.0 è consigliato.

  • Python 3.11+ installato

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

  • Dipendenze di Toolkit agenti Microsoft/Agent Framework

    L'esempio usato nella procedura dettagliata si basa sulle raccolte di Agent Framework fornite tramite Toolkit agenti di Microsoft 365 o ATK. Questi file verranno installati automaticamente quando si usa l'estensione Toolkit agenti in VS Code per eseguire lo scaffolding dell'esempio oppure è possibile installare il pacchetto manualmente usando questo comando:

    uv pip install -e . --find-links ../dist --pre

  • Accesso a GitHub

  • Un progetto agente IA esistente. Questa Guida introduttiva usa un agente di esempio di Agent 365 dal Toolkit degli agenti di Microsoft 365 noto anche come ATK in VS Code.

  • CLI di A365

  • Autenticazione dell'identità dell'agente

Configurare il framework agente e l'esempio Python da Toolkit agenti di Microsoft 365

Per preparare tutti gli elementi, installare Toolkit agenti di Microsoft 365 in VS Code, aprire la raccolta di esempi e eseguire lo scaffolding dell'esempio Framework agente + Python in locale, in modo da poterlo configurare ed eseguirlo in un secondo momento. Gli screenshot seguenti mostrano ciò che ci si aspetta di vedere mentre si procede.

  1. Apri Visual Studio Code, quindi apri il pannello EstensioniCTRL+MAIUSC+X.

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

    Screenshot della ricerca di Estensioni Marketplace per Toolkit agenti.

  3. Seleziona Toolkit agenti di Microsoft 365.

  4. Selezionare 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 agenti di M365 viene visualizzata nella barra di spostamento 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 scorri per trovare l'esempio dell'agente Agent Framework + Python.

  9. Selezionarlo.

    Avrai due opzioni: Crea (scaffolding locale) o Visualizza in GitHub.

  10. Scegliere Create.

    Screenshot dell'agente Agent Framework con A365 SDK con l'esempio Python.

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

    Il toolkit esegue lo scaffolding dell'esempio Agent Framework + Python in una sottocartella (ad esempio sample_agent) e quindi aprila automaticamente in VS Code.

    Al termine dello scaffolding, è ora disponibile un progetto dell'agente Agent Framework + Python completamente funzionante nel computer

  12. Installare i pacchetti Agent 365 necessari

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

    Dopo aver esaminato il file package.json, installa tutti gli elementi eseguendo questo comando:

    uv pip install -e

    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

Aggiungi gli strumenti di Microsoft 365 (server MCP)

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

Quando usi i server 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

Sottoscrizione di notifica e gestione

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."

Osservabilità

Questo frammento mostra le modifiche minime necessarie per abilitare l'osservabilità nell'esempio. Inizializza l'SDK Osservabilità di Agent 365 ed esegue il wrapping di ogni chiamata dell'agente in InferenceScope in modo che gli input, gli output e i metadati possano essere acquisiti automaticamente.

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 è la configurazione completa dell'osservabilità necessaria per l'esempio di Python + Agent Framework. Ulteriori informazioni sull'osservabilità

Testare l'agente

Imposta le variabili di ambiente necessarie, seleziona una modalità di autenticazione e avvia l'agente in locale. Puoi testare tutti gli elementi end-to-end con Playground agenti senza disporre di un tenant di Microsoft 365, a meno che non voglia pubblicare l'agente e usarlo nelle 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 un nodo per l'autenticazione. Per lo sviluppo locale, l'esempio supporta l'autenticazione agentic usando i valori creati dal progetto agent.
  • Avvia l'agente in locale, che lo espone agli strumenti come Playground per gli agenti.
  • Usa Playground per gli agenti per testare messaggi, strumenti e notifiche senza configurare un tenant o distribuirlo.
  • Quando sei pronto per il comportamento reale, pubblica un tenant di Microsoft 365 e testa l'agente all'interno di Teams, Outlook o altri programmi Microsoft 365.

Altre informazioni sui test

Pubblicare l'agente

Quando l'agente è pronto per le esperienze effettive di Microsoft 365, ad esempio chat di Teams, messaggi di Outlook, Word @mentions, viene pubblicato in un tenant di Microsoft 365. Il comando dell'interfaccia della riga di comando di Agent 365 publish gestisce la creazione del pacchetto: aggiorna il manifesto, aggrega tutto e carica l'agente nell'interfaccia di amministrazione Microsoft.

Durante la pubblicazione, esamina e personalizza il nome, la descrizione, le icone e la versione dell'agente prima di completare il caricamento. Dopo la pubblicazione, l'agente diventa individuabile 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. Vedi Configura il blueprint 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

  • Last updated on