Inicio rápido: Configuración y ejecución del agente de Ejemplo del SDK de Claude para JavaScript

En este inicio rápido, le guía a través de la configuración de un agente de Claude de JavaScript en funcionamiento mediante herramientas, notificaciones, observabilidad y prueba de Agent 365 mediante el área de juegos de Agents y Teams.

Requisitos previos

• Si tiene previsto usar Visual Studio Code, debe tener instalado .NET. (Se recomienda .NET 8.0)
• Node.js (versión 18 o superior)
• Paquetes del SDK de Claude Agent y una clave de API antropónica
• Área de juegos de agentes
• El acceso a instalaciones de npm (nodo Administrador de paquetes)
• Acceso a GitHub
• Un proyecto de agente de IA ya existente. En este inicio rápido se usa un agente de ejemplo de Claude de la galería del Kit de herramientas de Microsoft 365 Agents (ATK en VS Code).
• A365 CLI
• Autenticación de identidad del agente

Configuración del ejemplo Claude + Node.js del Kit de herramientas de Microsoft 365 Agents

Para prepararlo todo, instale el Kit de herramientas de Microsoft 365 Agents en VS Code, abra la galería de ejemplos y aplique scaffolding a Claude + Node.js ejemplo localmente para que pueda configurarlo y ejecutarlo más adelante. En las capturas de pantalla siguientes se muestra qué esperar mientras avanza por el flujo.

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

   

2. Abra la vista Kit de herramientas de M365 Agents en la barra de actividad de VS Code y elija Ver 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.

   

Una vez completada el scaffolding, 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 configurado en el ejemplo (localhost:3978 de forma predeterminada) y está listo para aceptar solicitudes del área de juegos de agentes 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 @microsoft/agents-a365-tooling-extensions-claude paquete conectan estos servidores MCP al orquestador de Claude para que el SDK del agente pueda llamar a las herramientas de Microsoft 365 alineadas con las aptitudes definidas en el plan del agente de Claude.

Al trabajar con servidores MCP, puede hacer lo siguiente:

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

Observabilidad

Este fragmento de código muestra los cambios mínimos necesarios para habilitar la observabilidad en el ejemplo. Actualiza src/client.ts para inicializar el SDK de observabilidad de Agent 365 y encapsula cada invocación de agente en un InferenceScope para que las entradas, salidas y metadatos se puedan capturar 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 es la configuración de observabilidad completa necesaria para el ejemplo de Node.js + Claude. Reemplace los metadatos del marcador de posición por los valores que ya configuró para el agente. Obtenga más información sobre la observabilidad

Pruebe 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 u Outlook.

Introducción a los pasos de prueba

• Agregue ANTHROPIC_API_KEY y la configuración del modelo a un archivo .env para que el ejemplo 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, que lo expone a herramientas como el área de juegos de agentes.
• Use Agents Playground para probar mensajes, herramientas y notificaciones sin configurar un inquilino ni implementar nada.
• Cuando esté listo para el comportamiento real, publique un inquilino de Microsoft 365 y pruebe el agente dentro de Teams, Outlook u otras superficies de Microsoft 365.

Más información sobre pruebas

Publicar su agente

Cuando el agente está listo para experiencias reales de Microsoft 365, como chats de Teams, mensajes de Outlook o Word @mentions, se publica en un inquilino de Microsoft 365. El comando Agent 365 CLI publish es un comando que controla el empaquetado: actualiza el manifiesto, agrupa todo y carga el agente en el 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 puede detectar e instalar dentro del inquilino.

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