Inicio rápido: Configura y ejecuta el agente de muestra para JavaScript del SDK de Claude

En esta guía rápida, le acompañará en la configuración de un agente de Claude en JavaScript funcional utilizando las herramientas de Agent 365, notificaciones, observabilidad, y probando el agente en el entorno de pruebas Agents Playground y Teams.

Prerequisites

Configurar el ejemplo de Claude + Node.js del kit de herramientas para agentes de Microsoft 365

Para prepararlo todo, instale el kit de herramientas de agentes de Microsoft 365 en VS Code, abra la galería de ejemplo y aplique scaffolding al ejemplo de Claude + Node.js localmente para que pueda configurarlo y ejecutarlo más adelante. Las capturas de pantalla siguientes muestran qué esperar a medida que avanza por el proceso.

  1. En Visual Studio Code, abra el panel de Extensiones (Ctrl+Shift+X), busque Microsoft 365 Agents Toolkit, luego seleccione Instalar.

    Captura de pantalla de la búsqueda en el mercado de Extensiones para Agents Toolkit.

  2. Abra la vista Kit de herramientas de M365 Agents en la barra de actividad de VS Code y elija Ver ejemplos.

    Captura de pantalla de la vista de bienvenida del kit de herramientas con crear un agente declarativo, crear un nuevo agente o aplicación y ver las opciones Ejemplos.

  3. Seleccione el ejemplo Claude + Node.js , elija Crear y elija (o cree) la carpeta donde se debe aplicar scaffolding al proyecto (por ejemplo, C:\A365-Ignite-Demo). El kit de herramientas crea una subcarpeta (como sample_agent) y la abre en VS Code.

    Captura de pantalla de los ejemplos del kit de herramientas del agente. Ejemplo de Claude resaltado.

Una vez completado el escafolding, tiene un proyecto ejecutable. Los pasos siguientes se realizan dentro de la nueva carpeta de ejemplo.

Instalar dependencias y configurar el entorno

El elemento generado package.json ya enumera los paquetes que necesita el ejemplo, por lo que debe instalar todo en un paso:

npm install

Después de la instalación, compruebe que el proyecto se compila y se ejecuta iniciando el servidor de desarrollo

npm run dev

El servidor de desarrollo escucha en el puerto que está configurado en el ejemplo (localhost:3978 de forma predeterminada) y está listo para aceptar solicitudes desde Agents Playground o la CLI.

Agregar herramientas de Microsoft 365 (servidores MCP)

Puede explorar y administrar servidores MCP mediante los comandos de desarrollo de a365 en la CLI. El paquete @microsoft/agents-a365-tooling-extensions-claude conecta estos servidores MCP al orquestador de Claude para que el SDK del agente pueda llamar a las herramientas de Microsoft 365 de acuerdo con las habilidades definidas en el plan del agente de Claude.

Cuando trabajas con las herramientas MCP de Microsoft, puedes:

  • Detectar qué servidores MCP están disponibles para su uso
  • Agregar uno o varios servidores MCP a la configuración del agente
  • Revisión de los servidores MCP configurados actualmente
  • Eliminación de servidores MCP que ya no necesita

Una vez agregados los servidores MCP, el manifiesto de herramientas del agente se expande para incluir entradas similares a:

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://00001111-aaaa-2222-bbbb-3333cccc4444"
    }
  ]
}

Aprenda a agregar y administrar herramientas

Suscripción y control de notificaciones

El agente de ejemplo se suscribe a todas las notificaciones de Agent 365 mediante onAgentNotification("*") y las enruta a un único controlador. Este controlador permite al agente reaccionar a los eventos de fondo o del sistema, no solo a los mensajes directos del usuario.

Obtenga información sobre cómo notificar a los agentes

El código siguiente muestra cómo se configura la notificación en el archivo 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

Esta muestra utiliza el SDK de observabilidad obsoleto de Agent 365. No uses este patrón para una nueva integración de observabilidad. Usa la distribución OpenTelemetry de Microsoft en su lugar.

El siguiente fragmento inicializa el obsoleto Agent 365 Observability SDK y envuelve cada invocación de agente en un InferenceScope para que las entradas, salidas y metadatos puedan capturarse automáticamente.

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

Este código utiliza la configuración obsoleta del SDK de observabilidad Agent 365 requerida para la muestra Node.js + Claude. Reemplace los metadatos del marcador de posición por los valores que ya configuró para el agente. Revisa la documentación obsoleta del SDK, incluyendo la guía de migración para Microsoft OpenTelemetry.

Probar el agente

Establezca las variables de entorno necesarias, seleccione un modo de autenticación e inicie el agente localmente. Puede probar todo de un extremo a otro con Agents Playground sin necesidad de un inquilino de Microsoft 365 a menos que quiera publicar el agente y usarlo en aplicaciones como Teams o Outlook.

Introducción a los pasos de prueba

  • Agregue ANTHROPIC_API_KEY y la configuración del modelo a un archivo .env para que la muestra pueda comunicarse con Claude.
  • Elija su modo de autenticación. Para el desarrollo local, el ejemplo admite la autenticación agentica mediante valores creados a partir del plano técnico del agente.
  • Inicie el agente localmente, lo que lo pone a disposición de herramientas como Agents Playground.
  • Use Agents Playground para probar mensajes, herramientas y notificaciones sin configurar un inquilino ni implementar nada.
  • Cuando esté listo para el comportamiento en el mundo real, publique una instancia de Microsoft 365 y pruebe el agente dentro de Teams, Outlook u otras plataformas de Microsoft 365.

Más información sobre pruebas

Publica tu agente

Cuando el agente esté listo para experiencias de Microsoft 365 reales, como chats de Teams, mensajes de Outlook o Word @mentions, lo publique en un tenant de Microsoft 365. El comando CLI publish Agent 365 se encarga del empaquetado: actualiza tu manifiesto, agrupa todo y sube el agente al centro de administración de Microsoft.

Durante la publicación, revise y personalice el nombre, la descripción, los iconos y la versión del agente antes de completar la carga. Una vez publicado, el agente se registra y se instala dentro del arrendatario.

Importante

Después de publicar tu agente, debes configurar el blueprint del agente en el Portal de Desarrolladores antes de crear instancias. Aprende cómo configurar el plan del agente en el Portal de Desarrolladores

Puede ver los agentes publicados aquí: https://admin.cloud.microsoft/#/agents/all

Más información sobre el flujo de trabajo completo y las instrucciones paso a paso

  • Se actualizó por última vez el