Guida introduttiva: configurare ed eseguire l'agente di esempio dell'SDK dell'agente JavaScript Claude

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.

Prerequisiti

Se prevedi di usare Visual Studio Code, è necessario che .NET sia installato. .NET 8.0 è consigliato.
Node.js versione 18 o superiore
Pacchetti SDK agenti Claude e una chiave API anthropic
Playground agenti
Accesso a installazioni npm (Nodo Gestione pacchetti)
Accesso a GitHub
Un progetto agente IA esistente. Questa guida introduttiva usa un agente di esempio Claude dalla raccolta di Toolkit agenti di Microsoft 365 (ATK in VS Code).
CLI di A365
Autenticazione dell'identità dell'agente

Configurare l'esempio Claude + 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 Claude + Node.js in locale, in modo da poterlo configurare ed eseguirlo in un secondo momento. Gli screenshot seguenti mostrano cosa aspettarsi durante lo spostamento nel flusso.

In Visual Studio Code, apri il riquadro Estensioni (CTRL+MAIUSC+X), cerca Toolkit agenti di Microsoft 365 e seleziona Installa.
Apri la visualizzazione Toolkit agenti M365 dalla barra delle attività di VS Code e scegli Visualizza esempi.
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.

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 dal Playground agenti o dall'interfaccia della riga di comando.

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

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. Aggiorna src/client.ts per inizializzare l'SDK dell'osservabilità di Agent 365 ed esegue il wrapping di ciascuna invocazione agente in un InferenceScope pertanto input, output e metadati possono essere acquisiti 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 è la configurazione completa dell'osservabilità necessaria per l'esempio Node.js + Claude. Sostituisci i metadati segnaposto con i valori già configurati per l'agente. 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 ANTHROPIC_API_KEY e le impostazioni del modello a un file .env in modo che l'esempio possa comunicare con Claude.
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 o 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

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-12-18