Quickstart: Configurar e executar 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 planeias usar Visual Studio Code, tens de ter o .NET instalado. É recomendado o TLS 1.2.
Node.js versão 20 ou superior
Pacotes Claude Agent SDK e uma chave API Anthropic
Parque infantil dos agentes
Acesso às instalações npm (Gestor de Pacotes de Node)
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

Configurar o exemplo Claude + Node.js a partir do Microsoft 365 Agents Toolkit

Para preparar tudo, instala o Microsoft 365 Agents Toolkit no VS Code, abre a galeria de exemplos e instala localmente o Claude + Node.js exemplo para poderes configurá-lo e executá-lo mais tarde. As capturas de ecrã abaixo mostram o que esperar à medida que avanças 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 vista do M365 Agents Toolkit a partir da Barra de Atividade VS Code e escolha 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 abre-a no VS Code.

Quando o andaime estiver concluído, tens um projeto executável. Os passos seguintes acontecem dentro da nova pasta de exemplos.

Instalar dependências e configurar o ambiente

O gerado package.json já lista os pacotes que o exemplo precisa, por isso instala tudo numa só passagem:

npm install

Após a instalação, verifica se o projeto se constrói e corre iniciando o dev server

npm run dev

O servidor de desenvolvimento escuta a porta configurada no exemplo (localhost:3978 por defeito) e está pronto para aceitar pedidos do Agents Playground ou da linha de comando.

Adicionar ferramentas Microsoft 365 (servidores MCP)

Pode explorar e gerir servidores MCP usando os comandos de desenvolvimento a365 na linha de código. O @microsoft/agents-a365-tooling-extensions-claude pacote liga estes servidores MCP ao teu orquestrador Claude para que o SDK do Agente possa ligar às ferramentas Microsoft 365 em linha com as competências definidas no teu plano de agente Claude.

Ao trabalhar com servidores MCP, pode:

Descubra quais os servidores MCP disponíveis para utilização
Adicione um ou mais servidores MCP à configuração do seu agente
Revise os servidores MCP atualmente configurados
Remova os servidores MCP de que já não precisa

Depois de adicionados servidores MCP, o manifesto de ferramentas do seu agente expande-se 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 gerir ferramentas

Subscrição e gestão de notificações

O agente de exemplo subscreve todas as notificações do Agente 365 usando onAgentNotification("*") e encaminha-as para um único handler. Este handler permite ao agente reagir a eventos em segundo plano ou do sistema, não apenas a mensagens diretas do utilizador.

Aprenda como notificar os agentes

O código seguinte mostra como a notificação está configurada no agent.ts ficheiro.

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 excerto mostra as alterações mínimas necessárias para permitir a observabilidade na amostra. Atualização src/client.ts para inicializar o SDK de Observabilidade do Agente 365 e envolver cada invocação do agente para InferenceScope que as 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 é a configuração completa de observabilidade necessária para a amostra Node.js + Claude. Substitui os metadados provisórios pelos valores que já configuraste para o agente. Saiba mais sobre observabilidade

Teste o seu agente.

Defina as variáveis de ambiente necessárias, selecione um modo de autenticação e inicie o agente localmente. Podes testar tudo de ponta a ponta com o Agents Playground sem precisares de um tenant Microsoft 365, a menos que queiras publicar o agente e usá-lo em aplicações como o Teams ou o Outlook.

Visão geral dos passos de teste

Adiciona as definições de e ANTHROPIC_API_KEY modelo a um .env ficheiro para que o sample possa comunicar com o Claude.
Escolhe o teu modo de autenticação. Para desenvolvimento local, o exemplo suporta Autenticação Agential usando valores criados a partir do seu Agent Blueprint.
Inicia o agente localmente, o que o expõe a ferramentas como o Agents Playground.
Usa o Agents Playground para testar mensagens, ferramentas e notificações sem configurar um tenant ou implementar nada.
Quando estiver pronto para comportamentos reais, publique um tenant Microsoft 365 e teste o agente dentro do Teams, Outlook ou outras superfícies Microsoft 365.

Saiba mais sobre testes

Publicar o seu agente

Quando o seu agente estiver pronto para experiências reais com o Microsoft 365, como chats no Teams, mensagens do Outlook ou Word @mentions, publica-o num tenant Microsoft 365. O comando Agent 365 CLI publish trata da embalagem: atualiza o seu manifesto, agrupa tudo e carrega o agente no Microsoft Admin Center.

Durante a publicação, revise e personalize o nome, descrição, ícones e versão do agente antes de concluir o carregamento. Uma vez publicado, o seu agente torna-se detectável e instalável dentro do inquilino.

Pode ver os agentes publicados aqui: https://admin.cloud.microsoft/#/agents/all

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

Feedback

Esta página foi útil?

Last updated on 2025-12-02