Início Rápido: Configure e execute o agente de exemplo do JavaScript Claude Agent SDK

Neste Quickstart, explique como configurar um agente JavaScript Claude funcional usando ferramentas do Agent 365, notificações, observabilidade e testar o agente usando o Agents Playground e Teams.

Prerequisites

  • Se você planeja usar Visual Studio Code, deve ter .NET instalado. (é recomendável .NET 8.0.)
  • Node.js versão 18 ou superior
  • Pacotes do SDK do Claude Agent e uma chave de API Anthropic
  • Espaço de prática de agentes
  • Acesso a instalações do npm (Node Gerenciador de Pacotes)
  • Acesso ao GitHub
  • Um projeto existente de agente de IA. Este início rápido usa um agente de exemplo Claude da galeria Microsoft 365 Agents Toolkit (ATK no VS Code).
  • A365 CLI
  • Autenticação da Identidade do Agente

Configurar o exemplo Claude + Node.js do pacote de ferramentas Microsoft 365 Agents

Para preparar tudo, instale o kit de ferramentas Microsoft 365 Agents no VS Code, abra a galeria de exemplos e faça o scaffold do exemplo Claude + Node.js localmente para que você possa configurá-lo e executá-lo mais tarde. As capturas de tela abaixo mostram o que esperar conforme você avança pelo fluxo.

  1. Em Visual Studio Code, abra o painel Extensões (Ctrl+Shift+X); procure Microsoft 365 Agents Toolkit e selecione Instalar.

    Captura de tela do Marketplace de Extensões para a busca de Agents Toolkit.

  2. Abra a visualização M365 Agents Toolkit na Barra de Atividade do VS Code e selecione Ver Exemplos.

    Captura de tela da Vista de Boas-Vindas do Toolkit com opções Construir um Agente Declarativo, Criar um Novo Agente ou App, e Visualizar Exemplos.

  3. Selecione o exemplo Claude + Node.js , escolha Criar e escolha (ou crie) a pasta onde o projeto deve ser estruturado (por exemplo, C:\A365-Ignite-Demo). O toolkit cria uma subpasta (como sample_agent) e a abre no VS Code.

    Captura de tela de exemplos do Agent Toolkit. Amostra de Claude em foco.

Quando a estrutura estiver concluída, você terá um projeto executável. Os próximos passos acontecem dentro da nova pasta de exemplos.

Instalar dependências e configurar o ambiente

O package.json já gerado lista os pacotes que o exemplo precisa, então instale tudo de uma vez só:

npm install

Após a instalação, verifique se o projeto é construído e executado iniciando o servidor de desenvolvimento

npm run dev

O servidor de desenvolvimento escuta na porta configurada no exemplo (localhost:3978 por padrão) e está pronto para aceitar solicitações do Agents Playground ou da Interface de Linha de Comando (CLI).

Adicionar ferramentas de Microsoft 365 (servidores MCP)

Você pode explorar e gerenciar servidores MCP usando os comandos a365 develop na linha de comando. O pacote @microsoft/agents-a365-tooling-extensions-claude conecta esses servidores MCP ao seu orquestrador Claude para que o SDK do agente possa chamar as ferramentas Microsoft 365 em conformidade com as habilidades definidas em seu plano de agente Claude.

Quando você trabalha com as ferramentas MCP da Microsoft, pode:

  • Descubra quais servidores MCP estão disponíveis para uso
  • Adicione um ou mais servidores MCP à configuração do seu agente
  • Revise os servidores MCP atualmente configurados
  • Remova os servidores MCP que você não precisa mais

Após a adição dos servidores MCP, o manifesto de ferramentas do seu agente se expande para incluir entradas semelhantes a:

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

Aprenda a adicionar e gerenciar ferramentas

Assinatura e gerenciamento de notificações

O agente de exemplo assina todas as notificações do Agente 365 usando onAgentNotification("*") e as encaminha para um único handler. Esse handler permite que o agente reaja a eventos em segundo plano ou do sistema, não apenas mensagens diretas do usuário.

Aprenda como notificar os agentes

O código a seguir mostra como a notificação é configurada no agent.ts arquivo.

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

Important

Esta amostra utiliza o SDK de Observabilidade Agent 365 que está obsoleto. Não use esse padrão para uma nova integração de observabilidade. Use a distribuição OpenTelemetry da Microsoft em vez disso.

O trecho a seguir inicializa o obsoleto SDK de Observabilidade do Agente 365 e envolve cada invocação de agente em um InferenceScope para que entradas, saídas e metadados possam ser capturados 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;
}

Este código usa a configuração obsoleta do SDK de observabilidade Agent 365 necessária para a amostra Node.js + Claude. Substitua os metadados provisórios pelos valores que você já configurou para o agente. Revise a documentação obsoleta do SDK, incluindo orientações de migração para o Microsoft OpenTelemetry.

Testar seu agente

Defina as variáveis de ambiente necessárias, selecione um modo de autenticação e inicie o agente localmente. Você pode testar tudo de ponta a ponta com o Agents Playground sem precisar de um locatário Microsoft 365, a menos que você queira publicar o agente e usá-lo em aplicativos como o Teams ou Outlook.

Visão geral das etapas do teste

  • Adicione suas ANTHROPIC_API_KEY configurações de modelo a um .env arquivo para que o exemplo possa se comunicar com o Claude.
  • Escolha seu método de autenticação Para desenvolvimento local, o exemplo suporta Autenticação Agêncica usando valores criados a partir do seu Blueprint do Agente.
  • Inicie o agente localmente, expondo-o a ferramentas como o Agents Playground.
  • Use o Agents Playground para testar mensagens, ferramentas e notificações sem configurar um tenant ou implantar nada.
  • Quando estiver pronto para o comportamento em cenários reais, publique um ambiente Microsoft 365 e teste o agente no Teams, Outlook ou outras interfaces do Microsoft 365.

Saiba mais sobre testes

Publique seu agente

Quando o agente estiver pronto para experiências de Microsoft 365 reais, como chats no Teams, mensagens no Outlook ou no Word @mentions, você o publicará em um tenant do Microsoft 365. O comando CLI publish do Agente 365 cuida da embalagem: ele atualiza seu manifesto, agrupa tudo e envia o agente para o centro de administração da Microsoft.

Durante a publicação, revise e personalize o nome, descrição, ícones e versão do agente antes de concluir o upload. Depois de publicado, seu agente se torna registrado e instalável dentro do locatário.

Important

Após publicar seu agente, você deve configurar o blueprint do agente no Portal de Desenvolvedores antes de criar instâncias. Aprenda como configurar o blueprint do agente no Portal do Desenvolvedor

Você pode ver agentes publicados aqui: https://admin.cloud.microsoft/#/agents/all

Saiba mais sobre o fluxo de trabalho completo e as instruções passo a passo

  • Última atualização em