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

Модуль Tooling помогает разработчикам находить, настраивать и интегрировать серверы Model Context Protocol (MCP) в рабочие процессы агентов ИИ. MCP-серверы раскрывают внешние возможности как инструменты, которые могут использовать агенты ИИ. Для обзора доступных серверов инструментов см. Agent 365 tooling servers.

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

Обзор

Интеграция Agent 365 Tooling следует следующему рабочему процессу:

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

Предпосылки

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

Настройка удостоверения агента

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

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

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

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

Настройка сервисного принципала

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

Это важно

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

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

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

  3. Запустите скрипт.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

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

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

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

Используйте CLI Agent 365 для обнаружения, добавления и управления 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 команда разработки.

Используйте mock tooling server для тестирования

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

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

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

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

Научитесь настраивать и настраивать сервер mock tooling.

Замечание

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

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

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

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

Пример:ToolingManifest.json

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

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

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

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

Замечание

CLI Agent 365 автоматически заполняет 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)

Параметры:

Параметр Type Description Ожидаемое значение Обязательный или необязательный
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 Tooling предоставляет выделенные пакеты расширений для различных фреймворков оркестрации:

Замечание

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

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

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

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

Python с OpenAI

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

1. Добавить операторы импорта

Добавьте необходимые импорты для доступа к модулю Tooling и расширениям 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.

Параметр Description
agent Инстанс агента OpenAI для регистрации инструментов.
agentic_app_id Уникальный идентификатор агента (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 Samples.

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

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

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

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

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

После интеграции инструментов MCP в ваш агент протестируйте вызовы инструментов, чтобы убедиться, что они работают правильно и работают в разных ситуациях. Следуйте руководству по тестированию , чтобы настроить свою среду. Затем сосредоточьтесь в основном на разделе вызовов инструментов тестирования , чтобы проверить, что ваши инструменты MCP работают как следует. Также посмотрите сервер mock tooling для тестирования подключения к серверу 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

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

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

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

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

    Узнайте о сервере mock tooling.

  • Проверьте права в административном центре

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

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

    Проверка

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