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.

Pré-requisitos

Se você pretende usar o Visual Studio Code, precisa ter o .NET instalado. (.NET 8.0 é recomendado.)
Node.js versão 20 ou superior
Pacotes do SDK do Claude Agent e uma chave de API Anthropic
Playground de agentes
Usar o Gerenciador de Pacotes do Nó (npm) para instalar o pacote
Acesso ao GitHub
Um projeto existente de agente de IA. Este quickstart utiliza um agente de exemplo Claude da galeria Microsoft 365 Agents Toolkit (ATK no VS Code).
A365 CLI
Autenticação da Identidade do Agente

Configure o exemplo Claude + Node.js do Microsoft 365 Agents Toolkit

Para deixar tudo pronto, instale o Microsoft 365 Agents Toolkit no VS Code, abra a galeria de exemplos e faça um andamie localmente no Claude + Node.js para poder configurá-lo e rodá-lo depois. As capturas de tela abaixo mostram o que esperar conforme você avança pelo fluxo.

No Visual Studio Code, abra o painel de Extensões (Ctrl+Shift+X), procure por Microsoft 365 Agents Toolkit e selecione Instalar.
Abra a visualização do Toolkit de Agentes M365 na Barra de Atividade do Código VS e escolha Visualizar 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 e configurar o ambiente de desenvolvimento

O gerado package.json já lista os pacotes que o exemplo precisa, então instale tudo em uma única passagem:

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 a porta configurada no exemplo (localhost:3978 por padrão) e está pronto para aceitar solicitações do Playground dos Agentes ou da linha de cli.

Adicionar ferramentas do Microsoft 365 (servidores MCP)

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

Ao trabalhar com servidores MCP, você 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
}

Observabilidade

Este trecho mostra as mudanças mínimas necessárias para possibilitar a observabilidade na amostra. Atualize src/client.ts para inicializar o SDK de Observabilidade do Agente 365 e envolva cada invocação do agente para InferenceScope 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;
}

Esse código é a configuração completa de observabilidade necessária para a amostra Node.js + Claude. Substitua os metadados provisórios pelos valores que você já configurou para o agente. Saiba mais sobre observabilidade

Testar o 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 tenant do Microsoft 365, a menos que queira publicar o agente e usá-lo em apps como 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 sample possa se comunicar com o Claude.
Escolha seu método de autenticação Para desenvolvimento local, o exemplo suporta Autenticação Agente usando valores criados a partir do seu Blueprint do Agente.
Comece o agente localmente, o que o expõe 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 real, publique um tenant do Microsoft 365 e teste o agente dentro do Teams, Outlook ou outras superfícies do Microsoft 365.

Saiba mais sobre testes

Publicar seu agente

Quando seu agente estiver pronto para experiências reais com o Microsoft 365, como chats no Teams, mensagens do Outlook ou Word @mentions, você publica isso em um locatário do Microsoft 365. O publish CLI do Agente 365 cuida da embalagem: 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, seu agente se torna detectável e instalável dentro do inquilino.

Importante

Após publicar seu agente, você deve configurar o blueprint do agente no Portal de Desenvolvedores antes de criar instâncias. Veja 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?

Last updated on 2025-12-19