Обзор инструментов агента для службы Foundry Agent

Инструменты расширяют возможности ваших агентов в службе Microsoft Foundry Agent Service. Агент самостоятельно использует модель Foundry для создания текста, но средства позволяют выполнять действия: поиск в Интернете, выполнение кода, запрос данных или вызов собственных API. В этой статье описываются средства, доступные типы инструментов, использование средства в агенте и управление проверкой подлинности. Он также представляет каталог инструментов Foundry, где вы обнаруживаете и настраиваете средства. Чтобы использовать средства, вам нужен доступ к проекту Foundry и разрешение на управление инструментами в этом проекте.

Что такое инструменты?

Инструмент — это возможность, которую агент может использовать во время беседы для выполнения конкретной задачи. Когда агент получает сообщение пользователя, модель Foundry, которая управляет агентом, решает, следует ли вызывать инструмент в соответствии с инструкциями агентa и доступными описаниями инструментов. Агент отправляет запрос средства, ваше приложение или служба выполняет его, и результат возвращается в беседу, чтобы агент мог продолжать работу с точной, актуальной информацией.

Средства позволяют агентам переходить за рамки создания текста. Например, агент может:

• Найдите в Интернете текущую информацию перед ответами.
• Запустите Python код для анализа набора данных и создания диаграммы.
• Запросите векторное хранилище данных ваших документов, чтобы основать его ответ на ваших данных.
• Вызовите внешний API для поиска записи клиента или создания запроса в службу поддержки.

Типы инструментов

Служба агента Foundry предоставляет две категории инструментов: встроенные средства, готовые к использованию после базовой настройки, и пользовательские средства, которые позволяют использовать собственные возможности.

Встроенные средства

Служба агента Foundry предоставляет встроенные средства в качестве предварительно настроенных возможностей. Вы включаете эти инструменты на вашем агенте, а служба обрабатывает выполнение. Эти средства не требуют внешнего размещения или пользовательского кода.

К наиболее часто используемым встроенным средствам относятся:

• Веб-поиск — добавьте веб-поиск в свой агент. Агент получает сведения в режиме реального времени из общедоступного веб-сайта и возвращает ответы с встроенными ссылки. Этот метод - рекомендуемый способ добавления веб-заземления. Для получения информации о дополнительных сценариях, таких как специфичная для рынка фильтрация, ознакомьтесь с привязкой средствами Bing и обзором веб-привязки.
• Код интерпретатор — пусть агенты записывают и запускают код Python в изолированной среде для анализа данных, математики и создания диаграмм.
• Поиск файлов — агенты, обогащенные знаниями из загруженных файлов или внутренних документов с помощью векторного поиска.
• Вызов функций — определение пользовательских функций, которые может вызывать агент. Приложение выполняет функцию и возвращает результат.

Полный список встроенных инструментов см. в разделе "Все встроенные средства".

Настраиваемые инструменты

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

Ниже перечислены наиболее распространенные варианты пользовательского инструмента:

• Протокол контекста модели (MCP) — подключение агента к средствам, размещенным на конечной точке сервера MCP. Это лучше всего подходит для средств, общих для нескольких агентов или поддерживаемых другой командой.
• Agent-to-Agent (A2A) (предварительная версия) — подключение вашего агента к другим агентам через конечные точки, совместимые с A2A, для межагентного взаимодействия.
• Средство OpenAPI — подключение агента к внешним API HTTP с помощью спецификации OpenAPI 3.0 или 3.1.

Полный список настраиваемых параметров инструментов см. в разделе "Все пользовательские инструменты".

Панель элементов (предварительная версия)

toolbox — это курируемый пакет средств, таких как веб-поиск, Поиск с использованием ИИ Azure, интерпретатор кода, поиск файлов, серверы MCP и средства OpenAPI, которые настраиваются один раз и предоставляются как единую конечную точку, совместимую с MCP. Вместо присоединения каждого средства к каждому определению агента определите коллекцию на панели элементов и подключите любой агент к конечной точке панели элементов. Так как панель элементов предоставляет конечную точку, совместимую с MCP, любая среда выполнения, поддерживающая MCP, может использовать ее, включая агенты, созданные с помощью платформы агента Microsoft, LangGraph, GitHub Copilot SDK и настраиваемый код.

Инструментальные панели поддерживают управление версиями. Создайте несколько версий, протестируйте новую версию на конечной точке, специфичной для версии, а затем установите её как версию по умолчанию, когда она будет готова. Агенты, подключающиеся к конечной точке потребителя Toolbox, автоматически получают предустановленную версию по умолчанию без изменений кода. Дополнительные сведения см. в разделе "Управление версиями панели элементов".

Централизованное управление проверкой подлинности для инструментов на панели элементов. Панель инструментов обрабатывает внедрение учетных данных, обновление маркера и применение политик во время выполнения с помощью Microsoft Entra ID и OAuth, поэтому агенты не нуждаются в управлении учетными данными для каждого средства по отдельности. Дополнительные сведения о проверке подлинности см. в разделе "Настройка проверки подлинности сервера MCP".

Инструкции по настройке см. в разделе "Создание и использование панели элементов Foundry".

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

Чтобы добавить средство в агент, добавьте его в список инструментов агента при создании или обновлении определения агента. В следующем примере создается агент с включенным средством поиска в Интернете и отправляется запрос:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create an agent with web search enabled
agent = project.agents.create_version(
    agent_name="web-search-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions="You are a helpful assistant that can search the web.",
        tools=[WebSearchTool()],
    ),
)

# Send a query
response = openai.responses.create(
    input="What are the latest updates to Microsoft Foundry?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)

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

Настройка поведения средства во время выполнения с помощью структурированных входных данных

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

Структурированные входные данные полезны при следующих случаях:

• Разные пользователи нуждаются в разных векторных хранилищах или файлах в зависимости от их контекста.
• Необходимо повторно использовать одну и ту же конфигурацию агента в разных средах: разработка, тестирование, производство.
• Конечные точки сервера MCP или маркеры проверки подлинности зависят от запроса.

Следующие свойства средства поддерживают настройку с помощью структурированных входных данных:

Например, определение агента с шаблонным векторным хранилищем:

{
  "tools": [
    {
      "type": "file_search",
      "vector_store_ids": ["vs_base_kb", "{{customer_kb}}"]
    }
  ],
  "structured_inputs": {
    "customer_kb": {
      "description": "Vector store ID for the customer's knowledge base",
      "required": true,
      "schema": { "type": "string" }
    }
  }
}

Во время выполнения укажите реальное значение:

{
  "agent": { "type": "agent_reference", "name": "support-agent", "version": "1" },
  "input": [{ "type": "text", "text": "How do I upgrade my account?" }],
  "structured_inputs": {
    "customer_kb": "vs_premium_kb_2024"
  }
}

Управление проверкой подлинности для инструментов

Для различных инструментов требуются различные подходы к проверке подлинности. Общие сведения об этих параметрах помогают безопасно подключать средства.

Встроенные средства

Большинство встроенных средств, таких как интерпретатор кода и поиск файлов, автоматически проходят проверку подлинности через службу агента Foundry и не требуют дополнительной настройки. Средства, которые подключаются к внешним источникам данных, например Поиск с использованием ИИ Azure или SharePoint, используют подключения, которые вы настраиваете в вашем проекте Foundry.

Серверы MCP

Серверы MCP поддерживают несколько методов проверки подлинности в зависимости от сервера: проверка подлинности на основе ключей (ключ API или маркер), проверка подлинности Microsoft Entra (управляемое удостоверение) и OAuth для сквозного удостоверения на уровне пользователя.

В следующем примере выполняется подключение к серверу MCP с помощью проверки подлинности на основе ключей. Сохраните учетные данные в подключении к проекту и используйте имя подключения при создании инструмента.

from azure.ai.projects.models import MCPTool

tool = MCPTool(
    server_label="github",
    server_url="https://api.githubcopilot.com/mcp",
    require_approval="always",
    project_connection_id="my-github-connection",
)

Для проверки подлинности Microsoft Entra используйте удостоверение агента или управляемое удостоверение проекта вместо подключения. Служба автоматически запрашивает маркер. Для пропуска идентификации OAuth (аутентификация по пользователю) служба агента создает ссылку согласия, которую пользователи авторизуют при первом обращении.

Подробные инструкции по настройке для всех методов см. в разделе "Настройка проверки подлинности сервера MCP".

Средства OpenAPI

Средства OpenAPI поддерживают анонимную аутентификацию, аутентификацию с использованием ключа API и управляемого удостоверения. Конфигурация проверки подлинности является частью определения средства.

Анонимная проверка подлинности — используйте, если API не требует учетных данных:

from azure.ai.projects.models import (
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

weather_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_weather",
        spec=openapi_spec,
        description="Retrieve weather information for a location.",
        auth=OpenApiAnonymousAuthDetails(),
    )
)

Проверка подлинности ключа API — храните ключ в подключении проекта, а затем сослаться на него. Спецификация OpenAPI должна включать securitySchemes и security разделы:

from azure.ai.projects.models import (
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiKeyAuthDetails,
)

api_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_orders",
        spec=openapi_spec,
        description="Look up customer orders.",
        auth=OpenApiKeyAuthDetails(
            project_connection_id="my-api-connection"
        ),
    )
)

Сведения о конфигурации управляемых удостоверений см. в разделе "Подключение агентов к средствам OpenAPI".

Все встроенные средства

В следующей таблице перечислены все встроенные средства, доступные в службе агента Foundry.

Все пользовательские инструменты

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

Основные понятия

Используйте эти определения, чтобы обеспечить согласованность терминологии:

Рекомендации по использованию не относящихся к Microsoft сервисов и серверов

Использование подключенных услуг и серверов, не связанных с Microsoft ("услуги, не связанные с Microsoft"), регулируется условиями между вами и поставщиком услуг. Услуги, не относящиеся к продуктам Microsoft, являются продуктами, не относящимися к Microsoft, в соответствии с вашим соглашением, регулирующим использование Microsoft онлайн-сервисов. При подключении к не-Microsoft-сервисам некоторые данные (например, содержимое запроса) отправляются в не-Microsoft-службу, или приложение может получать данные из не-Microsoft-службы. Вы несете ответственность за использование услуг, не относящихся к Microsoft, и данных, а также за все связанные с этим расходы.

Сторонние лица (не Microsoft) создают не-Microsoft службы, включая удаленные серверы MCP, к которым вы выбираете подключиться. Microsoft не тестирует или не проверяет эти серверы. Microsoft не несет ответственности перед вами или другими за использование вами любых услуг, не связанных с Microsoft.

Внимательно просмотрите и отслеживайте серверы MCP, которые вы добавляете в службу агента Foundry. Полагаться на серверы, размещенные доверенными поставщиками услуг, а не прокси-серверы.

Средство MCP может передавать пользовательские заголовки, которые может потребоваться удаленному серверу MCP для проверки подлинности. Обработайте все учетные данные как секреты:

• Укажите только минимальные обязательные заголовки.
• Не включайте учетные данные в запросы.
• Если вы регистрируете запросы на аудит, избегайте ведения журнала секретов или конфиденциального содержимого запроса.
• Просмотрите методики обработки данных поставщика, включая хранение и расположение данных.

Поиск и управление инструментами на портале

На портале Foundry перейдите к проекту и выберите"Средства>", чтобы открыть средства Foundry. В этом случае можно просмотреть каталог инструментов, настроить средства и добавить их в агенты или рабочие процессы. Если вам нужны инструменты, которые отображаются только в вашей организации, создайте частный каталог инструментов.

Чтобы изучить средства во время сборки, используйте игровую площадку Агентов. Дополнительные сведения см. в статье Microsoft Foundry Playgrounds.

Типы инструментов в каталоге

Каталог инструментов включает три типа записей:

Удаленный сервер MCP: издатель размещает сервер и предоставляет статическую или динамическую конечную точку. Следуйте инструкциям по настройке, чтобы указать необходимые параметры, такие как конечная точка и сведения о проверке подлинности.

Локальный сервер MCP: вы размещаете сервер самостоятельно, а затем подключите его к Foundry, предоставив ей конечную точку. Сведения о сборке и регистрации собственного сервера см. в статье "Сборка и регистрация сервера MCP". Сведения о подключении конечной точки MCP к агенту см. в разделе "Подключение к серверам MCP".

Custom: серверы MCP, преобразованные из коннекторов Azure Logic App. Для этих серверов требуется дополнительная конфигурация для преобразования в удаленные серверы MCP.

Фильтрация и поиск

Средства Foundry предоставляют следующие фильтры, которые помогут вам найти нужные инструменты:

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

Управление настроенными средствами

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

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

Доступность и ограничения

Доступность инструментов зависит от модели и региона.

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

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

Используйте эти проверки для устранения распространенных проблем:

• Не удается найти каталог инструментов: убедитесь, что вы находитесь в правильном проекте, а затем перейдите ксредствам>.
• Средство отображается, но его нельзя настроить: просмотрите необходимые входные данные проверки подлинности и конфигурации средства и убедитесь, что у вас есть доступ к любым зависимым службам.
• Агент не вызывает инструмент. Используйте руководства по проверке в лучших практиках использования инструментов в службе Foundry Agent.

Связанное содержимое

• Лучшие практики использования инструментов для службы агента Foundry
• Создание и использование панели элементов Foundry (предварительная версия)
• Настройка проверки подлинности сервера MCP
• Управление инструментами MCP с помощью шлюза искусственного интеллекта
• Создание каталога частных инструментов
• Создание и регистрация сервера MCP
• Лучшие практики и рекомендации по обеспечению безопасности для сервера Foundry MCP