Краткое руководство: настройка и запуск образца агента на JavaScript с помощью пакета SDK агентов Claude

Из этого краткого руководства вы узнаете, как настроить рабочий агент Claude на JavaScript с использованием инструментов Agent 365, уведомлений и наблюдаемости, а также как протестировать агент с помощью Agents Playground и Teams.

Prerequisites

Настройка примера Claude + Node.js из набора инструментов для создания агентов Microsoft 365

Чтобы подготовить все необходимое, установите набор инструментов для создания агентов Microsoft 365 в VS Code, откройте галерею примеров и создайте локально проект Claude + Node.js, чтобы затем его настроить и запустить. Снимки экрана ниже показывают, что вас ожидает в ходе выполнения потока.

  1. В Visual Studio Code откройте панель Расширения (сочетание клавиш Ctrl+Shift+X), найдите набор инструментов для создания агентов Microsoft 365 и выберите Установить.

    Снимок экрана поиска расширения набора инструментов для создания агентов в магазине расширений.

  2. Откройте раздел набор инструментов для создания агентов M365 на панели действий VS Code и выберите Просмотреть примеры.

    Снимок экрана приветственного представления набора инструментов с вариантами:

  3. Выберите пример Claude + Node.js, нажмите Создать и выберите (или создайте) папку, в которой должен быть сгенерирован проект (например, C:\A365-Ignite-Demo). Набор инструментов создает вложенную папку (например, sample_agent) и открывает ее в VS Code.

    Снимок экрана образцов набора инструментов для создания агентов. Выделен пример Claude.

После завершения подготовки шаблона у вас будет готовый к запуску проект. Следующие шаги выполняются внутри новой папки с примером.

Установите зависимости и настройте среду

Сгенерированный package.json уже включает необходимые пакеты для примера, поэтому установите все одной командой:

npm install

После установки убедитесь, что проект собирается и запускается, запустив сервер разработки

npm run dev

Сервер разработки слушает порт, настроенный в примере (по умолчанию localhost:3978), и готов принимать запросы от Agents Playground или интерфейса командной строки.

Добавление инструментов Microsoft 365 (серверы MCP)

Вы можете исследовать MCP-серверы и управлять ими с помощью команд разработчика a365 в интерфейсе командной строки. Пакет @microsoft/agents-a365-tooling-extensions-claude подключает эти MCP-серверы к вашему оркестратору Claude, чтобы Agent SDK мог вызывать инструменты Microsoft 365 в соответствии с навыками, определенными в вашем плане агента Claude.

Когда вы работаете с инструментами Microsoft MCP, вы можете:

  • Узнавать, какие MCP-серверы доступны для использования
  • Добавлять один или несколько MCP-серверов в конфигурацию вашего агента
  • Просматривать настроенные MCP-серверы
  • Удалять MCP-серверы, которые вам больше не нужны

После добавления MCP-серверов манифест инструментов вашего агента расширяется и включает записи, такие как:

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

Узнайте, как добавлять инструменты и управлять ими

Подписка на уведомления и их обработка

Пример агента подписывается на все уведомления Agent 365 с помощью onAgentNotification("*") и направляет их в один обработчик. Этот обработчик позволяет агенту реагировать на фоновые или системные события, а не только на прямые сообщения пользователя.

Подробнее о том, как отправлять уведомления агентам

В следующем коде показано, как настроено уведомление в файле agent.ts.

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

Этот выборка использует устаревший SDK Agent 365 Observability. Не используйте этот паттерн для новой интеграции наблюдаемости. Используйте дистрибутив Microsoft OpenTelemetry вместо этого.

Следующий фрагмент инициализирует устаревший SDK Observability Agent 365 и обертывает каждый вызов агента в такую InferenceScope систему, что позволяет автоматически фиксировать входы, выходы и метаданные.

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;
}

Этот код использует устаревшую систему Agent 365 Observability SDK, необходимую для выборки Node.js + Claude. Замените метаданные-заглушки на значения, которые вы уже настроили для агента. Ознакомьтесь с устаревшей документацией SDK, включая руководство по миграции для Microsoft OpenTelemetry.

Проверьте своего агента

Задайте необходимые переменные среды, выберите режим аутентификации и запустите агент локально. Вы можете провести комплексное тестирование с помощью Agents Playground без необходимости иметь арендатор Microsoft 365, если только не хотите опубликовать агент и использовать его в таких приложениях, как Teams или Outlook.

Обзор этапов тестирования

  • Добавьте значения ANTHROPIC_API_KEY и параметры модели в файл .env, чтобы пример мог обращаться к Claude.
  • Выберите режим аутентификации. Для локальной разработки этот пример поддерживает агентную аутентификацию с использованием значений, полученных из схемы агента.
  • Запустите агент локально, после чего он станет доступен инструментам, например Agents Playground.
  • Используйте Agents Playground для тестирования сообщений, инструментов и уведомлений без настройки арендатора или развертывания каких-либо компонентов.
  • Когда вы будете готовы к работе в реальных условиях, опубликуйте агент в арендаторе Microsoft 365 и протестируйте его внутри Teams, Outlook или других приложений Microsoft 365.

Подробнее о тестировании

Опубликовать вашего агента

Когда ваш агент готов к работе в среде Microsoft 365, например, для чатов Teams, сообщений Outlook или Word @mentions, вы публикуете его в арендаторе Microsoft 365. Команда publish интерфейса командной строки Agent 365 отвечает за упаковку: она обновляет ваш манифест, объединяет все и отправлять агент в центр администрирования Microsoft.

Во время публикации проверьте и измените имя агента, описание, значки и версию перед завершением отправки. После публикации ваш агент становится зарегистрированным и доступным для установки в арендаторе.

Important

После публикации агента необходимо настроить шаблон агента на портале разработчика перед созданием экземпляров. Узнайте, как настроить схему агента на портале разработчика

Здесь вы можете посмотреть опубликованные агенты: https://admin.cloud.microsoft/#/agents/all

Узнайте больше о полном рабочем процессе и пошаговых инструкциях

  • Последнее обновление: