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.

Prerequisiti

• Se prevedi di usare Visual Studio Code, è necessario che .NET sia installato. .NET 8.0 è consigliato.
• Node.js versione 18 o superiore
• LangChain
• Playground agenti
• L'accesso a Npm (Nodo Gestione pacchetti) viene installato con NodeJS
• 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 l'esempio LangChain + Node.js 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 LangChain + Node.js 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:

   

3. Seleziona Toolkit agenti di Microsoft 365.

4. Selezionare Installa.

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

   

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:

   

7. Seleziona Visualizza esempi.

8. Scorri l'elenco degli esempi per trovare l'esempio di agente LangChain + Node.js.

9. Selezionarlo.

   Avrai due opzioni: Crea (scaffolding locale) o Visualizza 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 esegue lo scaffolding dell'esempio LangChain + Node.js in una sottocartella (ad esempio sample_agent) e quindi aprila 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 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 package.jsoninstalla tutti gli elementi 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

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 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
}

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 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 modello principale per abilitare l'osservabilità nell'esempio Node.js + LangChain. Per la configurazione completa dell'osservabilità, vedi Altre 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. 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 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.

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