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
Playground 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 do Claude da galeria Kit de Ferramentas para Agentes do Microsoft 365 (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.

Em Visual Studio Code, abra o painel Extensões (Ctrl+Shift+X); procure Microsoft 365 Agents Toolkit e selecione Instalar.
Abra a visualização M365 Agents Toolkit na Barra de Atividade do VS Code e selecione Ver Exemplos.
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.

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 do Claude para que o SDK do Agente possa chamar as ferramentas do Microsoft 365 em conformidade com as habilidades definidas em seu plano de agente do 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 o Microsoft OpenTelemetry Distro.

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 configurações de ANTHROPIC_API_KEY e modelo a um arquivo .env 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 tudo estiver pronto para o comportamento real, publique um locatário do Microsoft 365 e teste o agente dentro do Teams, do Outlook ou de 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. Uma vez publicado, o agente fica 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

Comentários

Esta página foi útil?

Última atualização em 2026-10-20