Avvio rapido: configurare ed eseguire l'agente di esempio JavaScript Claude SDK

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

Prerequisites

Configurare l'esempio Claude + Node.js dal Toolkit degli Agenti di Microsoft 365

Per preparare tutti gli elementi, installare Microsoft 365 Agents Toolkit in VS Code, aprire la raccolta di esempi e eseguire lo scaffolding dell'esempio Claude + Node.js in locale in modo da poterlo configurare ed eseguirlo in un secondo momento. Gli screenshot seguenti mostrano cosa aspettarsi mentre si procede nel processo.

  1. In Visual Studio Code, apri il pannello Extensions (Ctrl+Shift+X), cerca Microsoft 365 Agents Toolkit e seleziona Installa.

    Screenshot della ricerca di Estensioni Marketplace per Toolkit agenti.

  2. Apri la visualizzazione M365 Agents Toolkit dalla barra delle attività di VS Code e scegli Visualizza esempi.

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

  3. Seleziona l'esempio Claude + Node.js, scegli Crea e seleziona (o crea) la cartella in cui deve essere sottoposto a scaffolding del progetto (ad esempio, C:\A365-Ignite-Demo). Il toolkit crea una sottocartella (ad esempio sample_agent) e la apre in VS Code.

    Screenshot degli esempi di Toolkit agenti. Esempio Claude in primo piano.

Dopo aver completato lo scaffolding, si dispone di un progetto eseguibile. I passaggi successivi vengono eseguiti all'interno della nuova cartella di esempio.

Installare le dipendenze e configurare l'ambiente

package.json generato elenca già i pacchetti necessari per l'esempio, quindi installa tutti gli elementi in un unico passaggio:

npm install

Dopo l'installazione, verifica che il progetto venga compilato ed eseguito avviando il server di sviluppo

npm run dev

Il server di sviluppo è in ascolto sulla porta configurata nell'esempio (localhost:3978 per impostazione predefinita) ed è pronto ad accettare richieste da Agent's Playground o dall'interfaccia della riga di comando.

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. Il pacchetto @microsoft/agents-a365-tooling-extensions-claude collega questi server MCP all'agente di orchestrazione Claude in modo che Agent SDK possa chiamare strumenti Microsoft 365 in linea con le competenze definite nel piano dell'agente Claude.

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.

import {
  InferenceOperationType,
  InferenceScope,
  ObservabilityManager
} from '@microsoft/agents-a365-observability';

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 codice utilizza la configurazione obsoleta dell'SDK di osservabilità Agent 365 richiesta per l'esempio Node.js + Claude. Sostituisci i metadati segnaposto con i valori già configurati per l'agente. Consulta la documentazione SDK obsoleta, inclusa la guida per la migrazione di Microsoft OpenTelemetry.

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 ANTHROPIC_API_KEY e le impostazioni del modello a un file .env in modo che l'esempio possa comunicare con Claude.
  • Scegli la modalità di autenticazione. Per lo sviluppo locale, l'esempio supporta Agentic Authentication utilizzando i valori creati dal tuo Agent Blueprint.
  • 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 o Word @mentions, pubblicarlo 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: