Início rápido: Configure e execute o agente de exemplo JavaScript LangChain

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

Prerequisites

Configurar o exemplo LangChain + Node.js do kit 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 LangChain + Node.js localmente para que você possa configurá-lo e executá-lo mais tarde. As capturas de tela a seguir mostram o que você deve esperar ver ao longo do caminho.

  1. Abra Visual Studio Code em seguida, abra o painel ExtensionsCtrl+Shift+X.

  2. Na barra de busca, digite "Agents Toolkit".
    Você deve ver o resultado mostrado na captura de tela aqui:

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

  3. Selecione Microsoft 365 Agents Toolkit.

  4. Selecione Instalar.

    O VS Code mostra a visualização de detalhes da extensão de forma semelhante a:

    Captura de tela da página de detalhes da extensão com os botões Instalar e Ativar.

  5. Uma vez instalado, o ícone do M365 Agents Toolkit aparece na barra de navegação à esquerda.

  6. Selecione para abrir a experiência de boas-vindas.

    Agora você deve ver opções como Construir um Agente Declarativo, Criar um Novo Agente/App e Visualizar Exemplos, como mostrado aqui:

    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.

  7. Selecione Ver Amostras.

  8. Na lista de exemplos, role para encontrar o exemplo do agente LangChain + Node.js.

  9. Selecione-o.

    Você verá duas opções: Create (scaffold local) ou View no GitHub.

  10. Escolha Criar.

  11. Quando solicitado, selecione uma pasta na sua máquina onde a amostra deve ser gerada. Por exemplo: C:\A365-Ignite-Demo

    O toolkit estrutura a amostra LangChain + Node.js em uma subpasta (como sample_agent) e então a abre automaticamente no VS Code.

    Quando a estrutura estiver concluída, você agora terá um projeto LangChain + agente Node.js totalmente funcional na sua máquina

Instale os pacotes necessários do Agent 365

Antes de rodar o exemplo, abra o package.json no seu projeto e confirme que todas as dependências necessárias do Agent 365 e do framework Agent estão listadas. O exemplo gerado pelo kit de ferramentas do Microsoft 365 Agents já inclui essas entradas.

Depois de revisar o package.json, instale tudo executando:

npm install

Isso remove todas as bibliotecas do Agent 365, dependências do framework do Agent, componentes de hospedagem e quaisquer outras dependências definidas no exemplo. Após a instalação, verifique se o projeto é construído e executado iniciando o servidor de desenvolvimento

npm run dev

Adicionar ferramentas de Microsoft 365 (servidores MCP)

Você pode explorar e gerenciar servidores MCP usando os comandos a365 develop na linha de comando.

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.

O código a seguir mostra um exemplo de observabilidade simplificada no client.ts arquivo.

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 trecho mostra o padrão obsoleto do SDK de observabilidade do Agent 365 usado pela amostra Node.js + LangChain. Para a orientação completa de configuração e migração, veja a documentação do SDK descontinuado.

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. Consulte as etapas detalhadas em Saiba mais sobre os testes para configurar os testes dos agentes com o playground de agentes.

Visão geral das etapas do teste

  • Adicione suas chaves de API e configurações de modelo a um .env arquivo para que o modelo de exemplo possa se comunicar com um LLM.
  • Escolha seu método de autenticação Para desenvolvimento local, o exemplo suporta Autenticação Agential usando valores criados a partir do seu Agente Blueprint.
  • 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.

Publique seu agente

Quando o agente estiver pronto para experiências do Microsoft 365 reais, como chats do Teams, mensagens do Outlook, Word @mentions, você o publicará em um locatário 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

  • Última atualização em