Добавление инструментов и управление ими

Модуль "Инструменты" помогает разработчикам находить, настраивать и интегрировать серверы протокола контекста модели (MCP) в рабочие процессы агентов ИИ. MCP-серверы предоставляют внешние возможности в виде инструментов, которые агенты ИИ могут использовать. Обзор доступных серверов инструментов см. в разделе Серверы инструментов Agent 365.

Демонстрирует поток запросов и ответов

Обзор

Рабочий процесс интеграции инструментов Agent 365 выглядит следующим образом:

  1. Настройка MCP-серверов — используйте Agent 365 CLI для обнаружения и добавления MCP-серверов
  2. Генерация манифеста — CLI создает ToolingManifest.json в вашей папке проекта с конфигурациями серверов.
  3. Назначение разрешений схеме — глобальный администратор предоставляет разрешения OAuth2 схеме агента, выполняя a365 setup all (при первой настройке) или a365 setup permissions mcp (если схема уже существует). В любом случае, команда читает ToolingManifest.json и требует согласия администратора. Этот шаг всегда выполняется отдельно от добавления серверов в манифест.
  4. Интеграция в код — загрузите манифест и зарегистрируйте инструменты с помощью вашего оркестратора.
  5. Вызов инструментов — агент вызывает инструменты во время работы для выполнения операций.

Предварительные условия

Перед настройкой MCP-серверов убедитесь, что у вас есть:

  • Установленный и настроенный Agent 365 CLI
  • .NET 8.0 SDK или выше — скачать
  • Привилегии глобального администратора в вашем арендаторе Microsoft 365

Настройка идентификатора агента

Если вы используете агентскую аутентификацию, выполните процесс регистрации агента, чтобы создать идентификатор агента перед настройкой MCP-серверов. Этот процесс создает идентификатор агента Entra и пользователя агента, которые позволяют вашему агенту аутентифицироваться и получать доступ к инструментам MCP.

Настройка аутентификации OBO

Если вы используете аутентификацию On-Behalf-Of (OBO) вместо агентской аутентификации, ваш агент может получить доступ к инструментам MCP, используя делегированные пользовательские разрешения без учетной записи пользователя агента. В OBO-потоке агент использует делегированный токен пользователя для выполнения действий от его имени.

Для получения дополнительной информации о том, как работает поток OBO, см. раздел Потоки аутентификации. Образец реализации полностью см. в примере авторизации OBO в Пакете SDK агентов Microsoft 365.

Настройка субъекта-службы

Запустите скрипт для однократной настройки, чтобы создать субъект-службу для инструментов Agent 365 в вашем арендаторе.

Важно

Эта однократная операция для каждого арендатора требует привилегий Глобального администратора.

  1. Скачайте скрипт New-Agent365ToolsServicePrincipalProdPublic.ps1.

  2. Откройте PowerShell как администратор и перейдите в каталог скрипта.

  3. Выполните скрипт.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. При появлении запроса войдите в систему, используя свои учетные данные Azure.

После завершения ваш арендатор готов к разработке агентов и настройке MCP-серверов.

Настройка MCP-серверов

Используйте Agent 365 CLI для обнаружения, добавления и управления MCP-серверами для вашего агента. Полный список доступных MCP-серверов и их возможностей см. в каталоге MCP-серверов.

Обнаружение доступных серверов

Выведите список всех MCP-серверов, которые можно настроить:

a365 develop list-available

Добавление MCP-серверов

Добавьте один или несколько MCP-серверов в конфигурацию вашего агента:

a365 develop add-mcp-servers mcp_MailTools

Важно

Эта команда только обновляет ToolingManifest.json в вашей папке проекта — она не предоставляет никаких разрешений схеме. То, как применяются разрешения, зависит от того, на каком этапе процесса настройки вы находитесь:

  • Перед первоначальной настройкой: сначала выполните a365 develop add-mcp-servers, затем переходите к a365 setup all. Команда setup all включает шаг назначения разрешений MCP в рамках создания схемы.
  • Когда схема уже существует: глобальный администратор должен выполнить a365 setup permissions mcp отдельно. В файле a365.config.json администратора deploymentProjectPath должен указывать на папку проекта, содержащую обновленный ToolingManifest.json. Пока этот шаг не будет завершен, новые разрешения MCP-сервера не отображаются в схеме.

Вывод списка настроенных серверов

Просмотрите настроенные в настоящее время MCP-серверы:

a365 develop list-configured

Удаление MCP-серверов

Удалите MCP-сервер из конфигурации:

a365 develop remove-mcp-servers mcp_MailTools

Полный справочник по CLI см. в разделе Команда a365 develop.

Использование сервера имитации инструментов для тестирования

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

Сервер имитации предоставляет следующие преимущества для локальной разработки и тестирования:

  • Офлайн-разработка: тестируйте свой агент без подключения к интернету или внешних зависимостей.
  • Стабильное тестирование: получайте предсказуемые ответы для тестирования пограничных случаев.
  • Отладка: просмотр всех запросов и ответов в реальном времени
  • Быстрая итерация: нет необходимости ждать внешних API-вызовов или настраивать сложные тестовые среды.

Запустите сервер имитации инструментов с помощью команды a365 develop start-mock-tooling-server.

Узнайте, как установить и настроить сервер имитации инструментов.

Примечание

Следующие разделы по настройке манифестов и интеграции инструментов в агента работают одинаково, независимо от того, используете ли вы сервер имитации инструментов или реальные MCP-серверы. Задайте переменную среды MCP_PLATFORM_ENDPOINT так, чтобы она указывала на сервер имитации (например: http://localhost:5309) вместо рабочей конечной точки.

О манифесте инструментов

Когда вы запускаете a365 develop add-mcp-servers, CLI генерирует файл конфигурации ToolingManifest.json, содержащий настройки для всех MCP-серверов. Среда выполнения агента использует этот манифест для определения доступных серверов и способов аутентификации на них.

Структура манифеста

Пример: ToolingManifest.json

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://05879165-0320-489e-b644-f72b33f3edf0"
    }
  ]
}

Параметры манифеста

Каждая запись MCP-сервера содержит:

Параметр Описание
mcpServerName Отображаемое имя MCP-сервера.
mcpServerUniqueName Уникальный идентификатор экземпляра MCP-сервера.
scope Область OAuth, необходимая для доступа к возможностям MCP-сервера (например, McpServers.Mail.All для почтовых операций). Команда add-mcp-servers получает это значение из каталога MCP-серверов.
audience URI Microsoft Entra ID, идентифицирующий целевой ресурс API. Команда add-mcp-servers получает это значение из каталога MCP-серверов.

Примечание

Agent 365 CLI автоматически заполняет значения scope и audience при добавлении MCP-сервера. Эти значения поступают из каталога MCP-серверов и определяют права доступа к каждому MCP-серверу.

Интеграция инструментов в агента

После формирования манифеста инструментов интегрируйте настроенные MCP-серверы в код агента. В этом разделе описывается необязательный шаг проверки и обязательные шаги интеграции.

Вывод списка серверов инструментов (необязательно)

Совет

Этот шаг необязательный. Используйте службу конфигурации серверов инструментов, чтобы просмотреть доступные серверы инструментов из манифеста инструментов перед их добавлением в ваш оркестратор.

Используйте службу конфигурации серверов инструментов, чтобы определить, какие серверы инструментов доступны вашему агенту, из манифеста инструментов. Этот метод позволяет:

  • Запросить все настроенные MCP-серверы из файла ToolingManifest.json.
  • Извлечь метаданные и возможности серверов.
  • Проверить доступность серверов перед регистрацией.

Метод вывода списка серверов инструментов доступен в основных пакетах инструментов:

# Use McpToolServerConfigurationService.list_tool_servers
from microsoft.agents.a365.tooling import McpToolServerConfigurationService

config_service = McpToolServerConfigurationService()
tool_servers = await config_service.list_tool_servers(agentic_app_id, auth_token)

Параметры:

Параметр Тип Описание Ожидаемое значение Обязательный/необязательный
agentic_app_id str Уникальный идентификатор экземпляра приложения агента Действительная строка идентификатора приложения агента Обязательно
auth_token str Токен носителя для аутентификации через шлюз MCP-сервера Действительный токен носителя OAuth Обязательно

Пакет: microsoft_agents_a365.tooling

Регистрация инструментов в оркестраторе

Используйте метод расширения, специфичный для фреймворка, чтобы зарегистрировать все MCP-серверы в вашем фреймворке оркестрации:

  • AddToolServersToAgentAsync (.NET)
  • add_tool_servers_to_agent (Python)
  • addToolServersToAgent (Node.js)

Данные методы:

  • Регистрируют все инструменты с настроенных MCP-серверов в вашем оркестраторе
  • Автоматически настраивают аутентификацию и сведения для подключения
  • Сразу же делают инструменты доступными для вызова агентом

Выбор расширения оркестратора

Модуль инструментов Agent 365 предоставляет специальные пакеты расширений для различных оркестрационных фреймворков:

Примечание

При выполнении a365 develop add-mcp-servers CLI автоматически извлекает значения областей OAuth и аудиторий из каталога MCP-серверов и записывает их в ToolingManifest.json. Методы расширения используют эти значения для настройки аутентификации во время выполнения — ручная настройка в коде агента не требуется. Однако глобальный администратор должен предварительно предоставить эти разрешения схеме агента, прежде чем ваш агент сможет использовать их в рабочей среде: через a365 setup all (при первой установке) или a365 setup permissions mcp (если схема уже существует).

Подробные примеры реализации см. в примерах Agent 365.

Примеры реализации

Далее приведены примеры, показывающие, как интегрировать инструменты Agent 365 с различными фреймворками оркестрации.

Python с OpenAI

Этот пример показывает, как интегрировать инструменты MCP с OpenAI в приложении на Python.

1. Добавление операторов импорта

Добавьте необходимые импорты для доступа к модулю инструментов и расширениям OpenAI:

from microsoft.agents.a365.tooling import McpToolServerConfigurationService
from microsoft.agents.a365.tooling.extensions.openai import mcp_tool_registration_service

2. Инициализация служб инструментов

Создайте экземпляры служб конфигурации и регистрации инструментов:

# Create configuration service and tool service with dependency injection
self.config_service = McpToolServerConfigurationService()
self.tool_service = mcp_tool_registration_service.McpToolRegistrationService()

3. Регистрация инструментов MCP в агенте OpenAI

Используйте метод add_tool_servers_to_agent для регистрации всех настроенных MCP-инструментов в вашем агенте OpenAI. Этот метод обрабатывает как сценарии с агентской, так и с неагентской аутентификацией:

async def setup_mcp_servers(self, auth: Authorization, context: TurnContext):
    """Set up MCP server connections"""
    try:
        use_agentic_auth = os.getenv("USE_AGENTIC_AUTH", "false").lower() == "true"
        if use_agentic_auth:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
            )
        else:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
                auth_token=self.auth_options.bearer_token,
            )

    except Exception as e:
        logger.error(f"Error setting up MCP servers: {e}")

Параметры метода

В следующей таблице описываются параметры, используемые с add_tool_servers_to_agent.

Параметр Описание
agent Экземпляр агента ИИ OpenAI, в котором регистрируются инструменты.
agentic_app_id Уникальный идентификатор агента (ИД агентского приложения).
auth Контекст авторизации пользователя.
context Контекст текущего хода разговора из SDK агентов. Предоставляет информацию о пользователе, метаданные разговора и контекст аутентификации для безопасной регистрации инструмента.
auth_token (Опционально) Токен носителя для сценариев неагентской аутентификации.

4. Вызов во время инициализации

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

# Setup MCP servers during initialization
await self.setup_mcp_servers(auth, context)

Метод add_tool_servers_to_agent автоматически:

  • Загружает все MCP-серверы из файла ToolingManifest.json.
  • Регистрирует их инструменты в агенте OpenAI.
  • Настраивает аутентификацию на основе конфигурации манифеста.
  • Делает инструменты доступными вашему агенту для вызова.

Полные работающие примеры см. в репозитории примеров Agent 365.

Другие способы доступа к MCP-серверам Agent 365

Помимо Agent 365 SDK, вы можете получить доступ к серверам Agent 365 MCP через другие платформы разработки:

  • Visual Studio Code — напрямую подключайтесь к MCP-серверам для пользовательских рабочих процессов разработки.
  • Microsoft Copilot Studio — интегрируйте MCP-серверы в разговорные потоки с помощью малокодовой платформы.
  • Azure AI Foundry — используйте MCP-серверы с полной поддержкой SDK и расширенными возможностями оркестрации.

Полный обзор доступных MCP-серверов и вариантов интеграции на этих платформах см. в разделе Обзор серверов инструментов Agent 365.

Собственный (BYO) MCP-сервер

Функция "Собственный (BYO) MCP-сервер" позволяет регистрировать ваши внешние MCP-серверы в Microsoft Agent 365, чтобы ими можно было централизованно управлять, утверждать и отслеживать их в Центре администрирования Microsoft 365. Она обеспечивает маршрутизацию этих серверов через шлюз инструментов Agent 365, предоставляя администраторам контроль над утверждением, доступом и политиками, а специалистам по безопасности — возможность отслеживать использование через телеметрию. Как разработчик, вы можете зарегистрировать свой MCP-сервер с помощью Agent 365 CLI, после чего администратор проверит и утвердит регистрацию и предоставит необходимые разрешения. Утвержденный сервер затем может использоваться в поддерживаемых клиентских инструментах; при этом непрерывный мониторинг обеспечивает соответствие требованиям и прозрачность во всех интеграциях.

Полные инструкции см. в разделе Собственный (BYO) MCP-сервер.

Тестирование агента

После интеграции инструментов MCP в вашего агента протестируйте вызовы инструментов, чтобы убедиться, что они функционируют корректно и обрабатывают различные сценарии. Следуйте руководству по тестированию, чтобы настроить среду. Затем сосредоточьтесь в первую очередь на разделе Тестирование вызовов инструментов, чтобы проверить, что ваши инструменты MCP работают как следует. Также рассмотрите возможность использования сервера имитации инструментов для тестирования подключения к MCP-серверу и вызовов инструментов без обработки аутентификации.

Добавление наблюдаемости

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

Устранение неполадок

В этом разделе перечислены распространенные проблемы при настройке и использовании MCP-серверов и инструментов.

Совет

Руководство по устранению неполадок Agent 365 содержит общие рекомендации по устранению неполадок, лучшие практики и ссылки на материалы по устранению неполадок для каждого этапа жизненного цикла разработки Agent 365.

Проблемы с MCP-серверами и инструментами

Симптомы:

  • Сбои вызова инструментов.
  • Ошибки "MCP-сервер не найден".
  • Ошибки отказа в доступе при вызове инструментов.

Первопричина:

  • MCP-сервер не настроен.
  • Отсутствуют разрешения.
  • Субъект-служба не настроен.
  • Путаница между сервером имитации и рабочим сервером.

Решения: попробуйте следующие решения, чтобы устранить проблему.

  • Убедитесь, что MCP-серверы настроены

    Выведите список настроенных серверов; если какие-либо серверы отсутствуют, добавьте их.

    # List configured servers
a365 develop list-configured

# If empty, add required servers (example: Mail MCP server)
a365 develop add-mcp-servers mcp_MailTools

  • Убедитесь, что субъект-служба существует

    Убедитесь, что создан необходимый для инструментов субъект-служба.

    # Run the one-time setup script
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

  • Для ранней разработки и тестирования используйте серверы имитации

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

    # Start mock tooling server
a365 develop start-mock-tooling-server

# Update your .env
MCP_PLATFORM_ENDPOINT=http://localhost:5309

    Подробнее о сервере имитации инструментов.

  • Проверьте разрешения в центре администрирования

    Убедитесь, что у вашего агента есть необходимые разрешения в отношении MCP.

    • Убедитесь, что разрешения API схемы вашего агента на портале Azure включают все разрешения в отношении MCP-серверов.

    Проверка:

    # Test a tool call in Agents Playground
# Should execute without permission errors
  • Last updated on