Guida introduttiva: Configurare ed eseguire l'agente di esempio LangChain JavaScript

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

Prerequisites

Configurare un esempio di LangChain + Node.js dal Microsoft 365 Agents Toolkit

Per preparare tutti gli elementi, installare Microsoft 365 Agents Toolkit in VS Code, aprire la raccolta di esempi e eseguire lo scaffolding dell'esempio LangChain + Node.js in locale, in modo da poterlo configurare ed eseguire in un secondo momento. 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 di Estensioni Marketplace per Toolkit agenti.

  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. Scorri l'elenco degli esempi per trovare l'esempio di agente LangChain + Node.js.

  9. Seleziona.

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

  10. Scegliere Create.

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

    Il toolkit configura l'esempio LangChain + Node.js in una sottocartella (ad esempio sample_agent) e quindi lo apre automaticamente in VS Code.

    Al termine dello scaffolding, è ora disponibile un progetto dell'agente LangChain + Node.js completamente funzionante nel computer

Installare i pacchetti Agent 365 necessari

Prima di eseguire l'esempio, apri package.json 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.

Dopo aver esaminato package.json, installa tutto eseguendo:

npm install

In questo modo vengono estratte tutte le librerie di Agent 365, le dipendenze del framework di Agent, i componenti di hosting e tutte le altre dipendenze definite nell'esempio. Dopo l'installazione, verifica che il progetto venga compilato ed eseguito avviando il server di sviluppo

npm run dev

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

constructor() {
   super();

   this.onAgentNotification("agents:*", async(context, state, activity) => {

      await this.handleAgentNotificationActivity(context, state, activity);

   });
}

async handleAgentNotificationActivity(context, state, activity)
{
   await context.sendActivity("Received an AgentNotification!");

   // Add custom handling here
}

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 frammento inizializza l'SDK di osservabilità dell'Agente 365 obsoleto e avvolge ogni invocazione dell'agente all'interno di InferenceScope in modo che input, output e metadati possano essere catturati automaticamente.

Il codice seguente illustra un esempio di osservabilità semplificata nel file client.ts.

const sdk = ObservabilityManager.configure(b =>
   b.withService('<service-name>', '<version>')
);

sdk.start();

async invokeAgentWithScope(prompt: string) {

   const scope = InferenceScope.start(
      { 
         operationName: InferenceOperationType.CHAT, 
         model: '<llm-name>' 
      },
      { 
         agentId: '<agent-id>', 
         agentName: '<agent-name>', 
         conversationId: '<conv-id>' 
      },
      { tenantId: '<tenant-id>' }
   );

   const response = await this.invokeAgent(prompt);
   scope?.recordInputMessages([prompt]);
   scope?.recordOutputMessages([response]);
   scope?.recordResponseId(`resp-${Date.now()}`);
   return response;

}

Questo frammento mostra il pattern SDK di osservabilità Agent 365 obsoleto usato dal campione Node.js + LangChain. Per la guida completa su configurazione e migrazione, 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. Per informazioni dettagliate sui passaggi, vedi Altre informazioni sui test per configurare il test dell'agente con il playground degli agenti.

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.

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: