Microsoft Foundry

Microsoft Agent Framework поддерживает прямое выполнение вывода модели из конечных точек проектов Microsoft Foundry, а также управляемые службой агенты в службе агента Foundry Agent Service.

Начало работы

Добавьте необходимые пакеты NuGet в проект.

dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

Два типа агента

Интеграция с Microsoft Foundry предоставляет два различных шаблона использования:

Тип	Созданный тип	Описание	Используйте, когда
Агент ответов	ChatClientAgent	Приложение программно предоставляет модель, инструкции и средства во время выполнения AIProjectClient.AsAIAgent(...). Ресурс агента на стороне сервера не создается.	Вы владеете определением агента и хотите простой гибкой настройки. Это шаблон, используемый в большинстве примеров.
Агент Foundry (версия)	FoundryAgent	Управляемый сервером — определения агента создаются и версионируются на портале Foundry или программным способом.AIProjectClient.AgentAdministrationClient Передайте ProjectsAgentVersion или ProjectsAgentRecord или AgentReference в AIProjectClient.AsAIAgent(...).	Вам нужны строгие определения агентов с версиями, управляемые на портале Foundry, с помощью API службы

Агент откликов (прямое заключение)

Используйте AsAIAgent на AIProjectClient непосредственно с моделью и инструкциями. Это рекомендуемая отправная точка для большинства сценариев.

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            name: "Joker",
            instructions: "You are good at telling jokes.");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Предупреждение

DefaultAzureCredential удобно для разработки, но требует тщательного рассмотрения в рабочей среде. В рабочей среде рекомендуется использовать определенные учетные данные (например, ManagedIdentityCredential), чтобы избежать проблем с задержкой, непреднамеренной проверки данных аутентификации и потенциальных рисков безопасности из-за резервных механизмов.

Этот путь ориентирован на изначальное использование кода и не создает ресурс агента, под управлением сервера.

Агент Foundry (версионируемый)

Используйте собственные AIProjectClient.AgentAdministrationClient API из SDK для проектов ИИ, чтобы получить версионные ресурсы агентов, затем оберните их с помощью AsAIAgent. Агенты можно создавать и настраивать непосредственно на портале Foundry или программным способом.AIProjectClient.AgentAdministrationClient

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;

var aiProjectClient = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential());

// Retrieve an existing agent by name (uses the latest version automatically)
ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Это важно

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

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

ChatClientAgent Оба типа (ответы) и FoundryAgent (версия) являются стандартными AIAgent экземплярами и поддерживают все стандартные операции, включая сеансы, инструменты, ПО промежуточного слоя и потоковую передачу.

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));

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

Tools

Агенты Foundry, созданные с помощью AIProjectClient.AsAIAgent(...) (пути Responses), поддерживают стандартный интерфейс инструментов Agent Framework — см. обзор инструментов, где приведены полный список и матрица поддерживаемых функций. Для агентов Foundry, загруженных из версионированного определения агента (FoundryAgent), инструменты агента принадлежат определению агента Foundry, а не клиенту.

инструмент	Примечания
Средства функций	Supported.
Утверждение инструмента	Supported. Предоставляется клиентом чата, вызывающим функцию платформы.
Интерпретатор кода	Supported.
Поиск файлов	Supported.
Размещенные средства MCP	Supported.
Локальные средства MCP	Supported.
Наборы инструментов Foundry	Supported.

Ящики с инструментами

Note

Документация по набору инструментов Foundry .NET скоро появится.

Проект Foundry на Python

В Python все клиенты, относящиеся к Foundry, теперь располагаются в agent_framework.foundry.

• agent-framework-foundry предоставляет облачные соединители Foundry: FoundryChatClient, FoundryAgent, FoundryEmbeddingClientи FoundryMemoryProvider.
• agent-framework-foundry-local обеспечивает FoundryLocalClient выполнение модели на локальном уровне.

Это важно

На этой странице рассматриваются текущие клиенты Python для конечных точек проекта Foundry Microsoft, конечных точек моделей и службы агента Foundry. Если у вас есть автономная конечная точка ресурса OpenAI Azure (https://<your-resource>.openai.azure.com), воспользуйтесь руководством по Python на странице поставщика OpenAI. Если вы хотите локально запускать поддерживаемые модели, см. страницу "Локальный поставщик Foundry".

Шаблоны чата и агента Foundry в Python

Сценарий	фигура Python	Используйте, когда
Простое вывод с конечной точкой "Ответы Foundry"	Agent(client=FoundryChatClient(...))	Ваше приложение владеет определением агента, инструментами и циклом беседы, и вам нужна модель, развернутая в проекте Foundry.
Управляемые службой агенты в службе агента Foundry	FoundryAgent(...)	Вы хотите подключиться к объекту PromptAgent или HostedAgent, который создается и настраивается на портале Foundry или через API службы.

Installation

pip install agent-framework-foundry
pip install azure-identity

Тот же agent-framework-foundry пакет также включает в себя FoundryEmbeddingClient встраивания моделей Foundry для конечных точек.

Конфигурация

FoundryChatClient

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_MODEL="gpt-4o-mini"

FoundryAgent

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

Используйте FOUNDRY_AGENT_VERSION для агентов подсказок. Размещенные агенты могут опустить его.

FoundryEmbeddingClient

FOUNDRY_MODELS_ENDPOINT="https://<apim-instance>.azure-api.net/<foundry-instance>/models"
FOUNDRY_MODELS_API_KEY="<api-key>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"
FOUNDRY_IMAGE_EMBEDDING_MODEL="Cohere-embed-v3-english"  # optional

FoundryChatClient и FoundryAgent используют конечную точку проекта. FoundryEmbeddingClient использует отдельную конечную точку моделей.

Выберите нужный клиент Python

Сценарий	Предпочтительный клиент	Примечания
ресурс Azure OpenAI	OpenAIChatCompletionClient / OpenAIChatClient	Используйте страницу поставщика OpenAI.
вывод проекта Microsoft Foundry	Agent(client=FoundryChatClient(...))	Использует конечную точку "Foundry Responses".
агент Microsoft Foundry, управляемый менеджером службы	FoundryAgent	Рекомендуется для оперативных агентов и хостед-агентов.
Модельные векторы внедрения Microsoft Foundry для конечных точек	FoundryEmbeddingClient	Использует FOUNDRY_MODELS_ENDPOINT плюс FOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL.
Локальная среда выполнения Foundry	Agent(client=FoundryLocalClient(...))	См. Foundry Local.

Создание агента с помощью FoundryChatClient

FoundryChatClient подключается к развернутой модели в проекте Foundry и использует конечную точку ответов. Совместите его со стандартом Agent, когда приложение должно полностью управлять инструкциями, средствами и сессиями.

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://your-project.services.ai.azure.com",
        model="gpt-4o-mini",
        credential=AzureCliCredential(),
    ),
    name="FoundryWeatherAgent",
    instructions="You are a helpful assistant.",
)

FoundryChatClient — это путь Python Foundry-first для прямого вывода и поддерживает средства, структурированные выходные данные и потоковую передачу.

Tools

FoundryChatClient включает статические фабричные методы для каждого размещённого инструмента Foundry. Фабрики возвращают объекты инструментов SDK, которые вы передаёте в tools= на Agent или напрямую в client.get_response(..., tools=[...]). Для FoundryAgent, инструменты агента находятся в самом определении агента Foundry — см. раздел Что работает, а что нет с FoundryAgent.

Фабричные методы — это методы класса, поэтому для создания инструмента экземпляр не нужен:

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(credential=AzureCliCredential()),
    instructions="You can search the web and run code.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        FoundryChatClient.get_code_interpreter_tool(),
    ],
)

Поддержка инструментов

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

инструмент	Фабрика в FoundryChatClient	Status	Detail
Средства функций	n/a — передайте любой вызываемый объект Python или @ai_function	GA	Вызывается локально в процессе Python.
Утверждение инструмента	n/a — оборачивает существующие инструменты	GA	Работает с размещёнными средствами MCP и инструментами функций.
Интерпретатор кода	get_code_interpreter_tool	GA	Изолированное выполнение кода в Foundry.
Поиск файлов	get_file_search_tool	GA	Поиск отправленных файлов через хранилища векторов Foundry.
Поиск в Интернете	get_web_search_tool	GA	Привязка к веб-данным на базе Bing под управлением Microsoft. Только модели Azure OpenAI.
Генерация изображений	get_image_generation_tool	GA	Генерация изображений на платформе Foundry.
MCP на хостинге	get_mcp_tool	GA	Удаленный сервер MCP, вызываемый Foundry.
Локальный MCP	n/a — используйте MCPStreamableHTTPTool / MCPStdioTool	GA	Работает в вашем процессе; совместим с любым клиентом.
Наборы инструментов Foundry	MCPStreamableHTTPTool к конечной точке MCP панели инструментов	GA	Используется через MCP из FoundryChatClient; подключается на стороне сервера в FoundryAgent.
Заземление Bing	get_bing_grounding_tool	Experimental	Приведите собственный заземление с помощью ресурса Bing Search.
Пользовательский поиск Bing	get_bing_custom_search_tool	Preview	Bing заземление ограничено списком курируемых доменов.
Поиск с использованием ИИ Azure	get_azure_ai_search_tool	Experimental	Выполните поиск по индексу Поиск с использованием ИИ Azure через подключение Foundry.
SharePoint	get_sharepoint_tool	Preview	Основывайте ответы на контенте SharePoint.
Microsoft Fabric	get_fabric_tool	Preview	Запросить данные у агента данных Fabric.
Поиск памяти	get_memory_search_tool	Preview	Выполните поиск в хранилище памяти, управляемом Foundry.
Использование компьютера	get_computer_use_tool	Preview	Разрешите агенту работать в среде рабочего стола или браузера.
Автоматизация браузера	get_browser_automation_tool	Preview	Управляйте браузером через подключение к Azure Playwright.
Агент — агент (A2A)	get_a2a_tool	Preview	Вызов другого A2A-агента как инструмента.

Note

Экспериментальные фабрики служат обёртками для типов SDK GA Foundry, но сами эти обёртки могут измениться до выхода общедоступной версии. Фабрики предварительной версии инкапсулируют типы SDK Foundry, чья базовая функциональность находится на стадии предварительной версии и может измениться или быть удалена. Оба выдают ExperimentalWarning первый раз, когда они используются в процессе.

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

Foundry предоставляет три варианта заземления с поддержкой Bing. Выберите тот, который соответствует вашему сценарию:

• get_web_search_tool (GA) — вариант по умолчанию, не требующий настройки; ресурс Bing, управляемый Microsoft. Только модели Azure OpenAI. Ограничено user_location и search_context_size.
• get_bing_grounding_tool (экспериментальная) — используйте собственный ресурс Azure Bing Search для Grounding. Поддерживает count, freshness, market, set_lang и модели, не относящиеся к OpenAI Foundry.
• get_bing_custom_search_tool (предварительная версия) — используйте свой экземпляр Bing Custom Search, чтобы ограничить использование данных заранее отобранным набором доменов.

Все три отправляют данные поиска за пределами границы соответствия Azure. Ознакомьтесь с обзором функции web grounding, чтобы увидеть полное сравнение.

client = FoundryChatClient(credential=AzureCliCredential())

# Default (GA): minimal configuration
web_search = client.get_web_search_tool(
    user_location={"city": "Amsterdam", "country": "NL"},
    search_context_size="medium",
)

Генерирование изображений

get_image_generation_tool настраивает размещённый инструмент Foundry для генерации изображений. Модель создает изображение прямо в ответе — никакими дополнительными файлами не нужно управлять.

image_gen = FoundryChatClient.get_image_generation_tool(
    model="gpt-image-1",
    size="1024x1024",
    output_format="png",
    quality="high",
)

Обоснование с помощью Bing

get_bing_grounding_tool является оболочкой для средства Grounding with Bing Search Foundry. Вы самостоятельно создаёте ресурс Grounding with Bing Search и добавляете его как подключение проекта Foundry, а затем передаёте идентификатор подключения.

bing = FoundryChatClient.get_bing_grounding_tool(
    connection_id="/subscriptions/.../connections/my-bing",
    market="en-US",
    freshness="Day",
    count=10,
)

Пользовательский поиск Bing

get_bing_custom_search_tool ограничивает привязку к данным списком разрешённых источников, определённым в ресурсе Bing Custom Search.

bing_custom = FoundryChatClient.get_bing_custom_search_tool(
    connection_id="/subscriptions/.../connections/my-bing-custom",
    instance_name="docs-only",
    market="en-US",
)

Поиск с использованием ИИ Azure

get_azure_ai_search_tool позволяет агенту запрашивать индекс Поиск с использованием ИИ Azure через подключение проекта Foundry.

ai_search = FoundryChatClient.get_azure_ai_search_tool(
    index_connection_id="/subscriptions/.../connections/my-search",
    index_name="product-docs",
    query_type="vector_semantic_hybrid",
    top_k=5,
)

Sharepoint

get_sharepoint_tool основывает ответы на содержимом SharePoint, доступном через подключение Foundry к SharePoint.

sharepoint = FoundryChatClient.get_sharepoint_tool(
    connection_id="/subscriptions/.../connections/my-sharepoint",
)

Microsoft Fabric

get_fabric_tool подключает агента к агенту данных Microsoft Fabric через подключение Foundry, чтобы агент мог отвечать на вопросы о данных Fabric.

fabric = FoundryChatClient.get_fabric_tool(
    connection_id="/subscriptions/.../connections/my-fabric",
)

Поиск памяти

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

memory = FoundryChatClient.get_memory_search_tool(
    memory_store_name="user-preferences",
    scope="{{$userId}}",
)

Использование компьютера

get_computer_use_tool настраивает инструмент предварительного доступа Computer Use — модель может управлять средой рабочего стола или браузера посредством команд указателя и клавиатуры.

computer = FoundryChatClient.get_computer_use_tool(
    environment="browser",
    display_width=1280,
    display_height=800,
)

Браузерная автоматизация

get_browser_automation_tool подключает агент к ресурсу Azure Playwright Testing с помощью подключения Foundry. Агент может управлять реальным браузером через Playwright.

browser = FoundryChatClient.get_browser_automation_tool(
    connection_id="/subscriptions/.../connections/my-playwright",
)

Агент — агент (A2A)

get_a2a_tool предоставляет доступ к удалённому агенту A2A как к инструменту, чтобы агент Foundry мог обращаться к нему. Укажите либо base_url (и, при необходимости, agent_card_path), либо project_connection_id для сохранённого подключения A2A.

a2a = FoundryChatClient.get_a2a_tool(
    base_url="https://remote-agent.example.com",
    agent_card_path="/.well-known/agent-card.json",
)

Общие рекомендации по A2A, включая обнаружение, сеансы и потоковую передачу, см. на странице поставщика Agent-to-Agent.

Создание внедренных модулей с помощью FoundryEmbeddingClient

Используйте FoundryEmbeddingClient, когда требуется встраивание текста или изображения из конечной точки Foundry models.

from agent_framework.foundry import FoundryEmbeddingClient

async with FoundryEmbeddingClient() as client:
    result = await client.get_embeddings(["hello from Agent Framework"])
    print(result[0].dimensions)

Подключение к агенту, управляемому службой, с помощью FoundryAgent

Используйте FoundryAgent, когда определение агента находится в Foundry. Это рекомендуемый API Python для агентов Prompt и HostedAgents.

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    agent_version="1.0",
    credential=AzureCliCredential(),
)

Для HostedAgent не укажите agent_version и используйте вместо него имя размещенного агента.

Что работает и что не работает с FoundryAgent

FoundryAgent подключается к уже существующему в Foundry агенту (Prompt Agent или Hosted Agent). Определение агента — его инструкции и конфигурация его инструментов — находится в Foundry, а не в вашем Python-коде. Это означает, что некоторые функции уровня Agent работают иначе, чем в случае с Agent(client=FoundryChatClient(...)) или другими агентами, поддерживаемыми чат-клиентом.

Tools

Тип инструмента, переданный в FoundryAgent(...)	Behavior
FunctionTool (локальный вызываемый объект Python)	Поддерживается, но только если определение соответствующей функции уже существует в агенте Foundry. Среда выполнения Foundry определяет, какие инструменты предоставить модели, исходя из определения агента. Когда модель вызывает функцию, Foundry возвращает клиенту вызов инструмента, а фреймворк вызывает ваш локальный вызываемый объект Python в вашем процессе (не в Foundry), а затем отправляет результат обратно. Передача клиентского FunctionTool лишь предоставляет эту локальную реализацию — если функция не объявлена в агенте Foundry, модель никогда её не вызовет.
Размещенные средства (веб-поиск, интерпретатор кода, поиск файлов, MCP, создание изображений и т. д.)	Проигнорировано. Они должны быть настроены в самом определении агента Foundry, на портале Foundry или через API службы. Передача их на стороне клиента не влияет, так как среда выполнения Foundry знает только о средствах, подключенных к определению агента.

Короче говоря: нельзя добавлять новые инструменты на этапе создания. Каждый инструмент, который модель может вызывать, включая локальные функции Python, уже должен быть частью определения агента в Foundry. Передача FunctionTool в FoundryAgent(...) предоставляет только локальную реализацию, которая выполняется в процессе Python при вызове функции Foundry; она не регистрирует новое средство в агенте.

Поставщики контекстов

context_providers=[...] частично поддерживается. Будет ли работать поставщик контекста, зависит от того, что он пытается сделать:

Поведение поставщика контекста	Работает с FoundryAgent?
Добавляет дополнительный контекст в виде сообщений (например, извлечённая память, фрагменты RAG, сведения о профиле пользователя)	Yes. Внедрённый контекст передаётся вместе с запросом.
Сохраняет разговор или отслеживает его (например, записывая реплики во внешнее хранилище)	Yes. Выполняется локально в рамках обработки запроса/ответа.
Динамически добавляет инструменты (например, SkillsProvider или любой поставщик, который возвращает инструменты из invoking())	Нет, если только инструменты уже не являются частью определения агента Foundry. Среда выполнения Foundry запускает модель с использованием инструментов, подключённых к агенту в Foundry; инструменты, существующие только локально, недоступны модели и не будут вызываться.

Если вам нужен динамический выбор инструментов, загрузка навыков или любое другое поведение, которое зависит от добавления инструментов во время выполнения, используйте Agent(client=FoundryChatClient(...)) — в этом варианте цикл модели управляется локально и поддерживается полный набор типов инструментов и поставщиков контекста, добавляющих инструменты.

Параметры выполнения (default_options и agent.run(...) параметры)

Параметры, которые вы передаете в FoundryAgent(default_options=...) или в agent.run(..., **options) (например, temperature, top_p, max_tokens, instructions, tool_choice, response_format, metadata и т. д.), поддерживаются не все. Так как определение агента в Foundry является источником истины, многие варианты автоматически игнорируются.

Для агентов запроса платформа явно удаляет или переопределяет следующее перед отправкой запроса в API ответов Foundry:

Опция	Поведение с помощью FoundryAgent
model	Проигнорировано. Модель взята из определения агента Foundry.
tools, tool_choice, parallel_tool_calls	Отрезается от текста запроса. Инструменты должны быть указаны в определении агента Foundry (см. предыдущий раздел). FunctionTool Вызываемые объекты по-прежнему подключены локально для вызова функции, но сам список инструментов не отправляется в службу.
instructions и системные сообщения/сообщения разработчика	Проигнорировано. Собственные инструкции агента Foundry являются заслуживающими доверия. Сообщения системы или разработчика удаляются из списка сообщений перед отправкой запроса.
conversation_id	Используется и сопоставляется с сеансом агента Foundry, когда имеется в виду такой сеанс.
extra_body	Перенаправлено, объединено с полезной нагрузкой, заданной фреймворком agent_reference.
Параметры выборки (temperature, top_pmax_tokensseedfrequency_penaltypresence_penaltystop...), metadata, user, store, response_formatи т. д.	Перенаправлен в API ответов. Применяет ли Foundry их на самом деле, зависит от конфигурации агента и модели — определение агента может переопределить их или наложить на них ограничения, — поэтому не стоит рассчитывать на то, что они будут применены для Prompt Agent.

Для размещаемых агентов применяется то же удаление данных на стороне клиента, но всё остальное зависит от того, что реализовано в конкретном размещаемом агенте. Размещаемый агент может принять, проигнорировать или интерпретировать по-своему любой переданный ему параметр. Считайте параметры времени выполнения ориентировочными и проверяйте фактическое поведение по размещённому агенту, к которому вы обращаетесь.

Подсказка

Если вам нужен точный контроль над параметрами генерации, инструкциями или выбором инструментов для каждого запуска, настройте их в определении агента в Foundry или переключитесь на Agent(client=FoundryChatClient(...)), который поддерживает ChatOptions на всем протяжении процесса.

Подсказка

Практическое правило: если возможность зависит от изменения инструкций или инструментов агента при каждом запуске, она относится к Agent(client=FoundryChatClient(...)). Если определение агента фиксировано в Foundry и вам нужен только локальный вызов функции, а также контекст уровня сообщения, FoundryAgent — правильный выбор.

Подключение к агенту Foundry, развернутому (размещенному)

Для HostedAgents, которые запускают сеансы на стороне службы (/agents/{name}/sessions), используйте FoundryAgent с allow_preview=True, чтобы включить предварительную версию интерфейса Responses:

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    agent_name="my-hosted-agent",
    credential=AzureCliCredential(),
    allow_preview=True,
)

Если вам нужно самостоятельно управлять базовым сеансом службы ( например, для привязки сеанса к конкретному клиенту или пользователю), создайте сеанс с помощью API предварительной версии AIProjectClient и заключите его следующим agent.get_session(...)образом:

from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import VersionRefIndicator

service_session = await project_client.beta.agents.create_session(
    agent_name="my-hosted-agent",
    isolation_key="user-123",
    version_indicator=VersionRefIndicator(agent_version="1.0"),
)
session = agent.get_session(service_session.agent_session_id)

response = await agent.run("Hello!", session=session)

Подсказка

См. using_deployed_agent.py образец для полного примера, включая автоматическое разрешение последней версии.

Настройка пользовательского времени ожидания HTTP

По умолчанию FoundryAgent (и RawFoundryAgent) наследует встроенное время ожидания пакета SDK OpenAI (5 s connect / 600 s total). В многоэтапных диалогах или при медленном сетевом соединении это может проявляться как ConnectTimeout. Передайте timeout= (в секундах) во время строительства, чтобы переопределить его:

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    credential=AzureCliCredential(),
    timeout=120.0,  # seconds; set to None to use the SDK default
)

Значение применяется через with_options(timeout=...) к отдельной для каждого агента копии HTTP-клиента, поэтому это не влияет на других агентов или клиентов, которые используют один и тот же AIProjectClient.

Предупреждение

Старые поверхности совместимости, включая Python AzureAIClient, AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider и встраивание Azure AI, были удалены из текущего пространства имен agent_framework.azure. Для текущего кода на Python используйте FoundryChatClient, если приложение располагает инструкциями и инструментами, FoundryAgent, когда определение агента находится в Foundry, и FoundryEmbeddingClient для эмбеддингов моделей на конечных точках Foundry.

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

Как FoundryChatClient, так и FoundryAgent интегрируются со стандартными возможностями Python Agent, включая вызовы инструментов, сеансы и потоковую передачу данных. Для локальных сред выполнения используйте отдельную страницу локального поставщика Foundry.

Ящики с инструментами

Это важно

API панели инструментов являются экспериментальными. Поверхность может измениться в будущих выпусках.

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

Agent Framework охватывает только потребление — создание и обновление версий панели элементов выполняется через портал Foundry или необработанный azure-ai-projects пакет SDK (azure-ai-projects>=2.1.0).

FoundryAgent и FoundryChatClient

Тип агента	Поведение панели элементов
FoundryAgent (хостинг)	Прикрепление панели инструментов происходит на стороне сервера. Подключение на стороне клиента не требуется.
FoundryChatClient (прямое вывод)	Используйте MCPStreamableHTTPTool с конечной точкой MCP панели инструментов.

Два шаблона потребления

Pattern	Описание
Подключение размещённого агента	Конфигурации инструментов выполняются в среде выполнения Foundry. Подключите набор инструментов к размещённому агенту Foundry.
MCP	Используйте MCPStreamableHTTPTool с конечной точкой MCP панели инструментов. Работает с любым клиентом чата, а не только FoundryChatClient.

Прямой вывод через конечную точку MCP инструментария

Для FoundryChatClient прямого вывода наведите указатель MCPStreamableHTTPTool на конечную точку MCP панели элементов. Используйте allowed_tools на MCPStreamableHTTPTool, когда панель инструментов предоставляет доступ к инструментам, которые конкретный агент не должен использовать.

Путь потребления MCP

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

URL-адрес конечной точки MCP отображается на портале Foundry или соответствует формату:

https://<account>.services.ai.azure.com/api/projects/<project>/toolsets/<name>/mcp?api-version=v1

Так как клиент подключается напрямую к конечной точке инструментария Foundry, необходимо аутентифицироваться с использованием маркера доступа Entra ID через header_provider:

from azure.identity.aio import DefaultAzureCredential
from azure.identity.aio import get_bearer_token_provider
from agent_framework import Agent, MCPStreamableHTTPTool

credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")

mcp_tool = MCPStreamableHTTPTool(
    name="research_mcp",
    url="https://<your-toolbox-mcp-endpoint>",
    header_provider=lambda _kwargs: {"Authorization": f"Bearer {token_provider()}"},
)

async with Agent(client=client, name="MCPAgent", tools=[mcp_tool]) as agent:
    result = await agent.run("Search for recent papers on LLM agents.")
    print(result.text)

Ограничения

• Средства MCP в инструментальной панели используют проверку подлинности на стороне сервера. Проверка подлинности на вышестоящем сервере MCP обрабатывается через project_connection_id (подключение OAuth, настроенное в проекте Foundry). Клиент никогда не хранит токены носителя для вышестоящего сервера.
• Для использования набора инструментов в качестве сервера MCP требуется проверка подлинности на стороне клиента. Когда вы направляете MCPStreamableHTTPTool на конечную точку MCP инструментария, необходимо предоставить маркер доступа Entra ID (например, через get_bearer_token_provider(credential, "https://ai.azure.com/.default")) с использованием header_provider.
• Обработка потока согласия является проблемой среды выполнения. Если инструмент MCP панели инструментов активируется CONSENT_REQUIRED во время agent.run() выполнения, он обрабатывается в это время, а не в процессе загрузки инструментов.

Samples

Sample	Описание
foundry_chat_client_with_toolbox.py	Использование набора инструментов MCP с MCPStreamableHTTPTool
foundry_chat_client_with_toolbox_skills.py	Настройка навыков на основе панели инструментов
invoke_foundry_toolbox_mcp	Траектория потребления MCP с MCPStreamableHTTPTool

Литейные в Go

SDK для Go предоставляет доступ к агентам Microsoft Foundry через github.com/microsoft/agent-framework-go/provider/foundryprovider.

Пакет поддерживает два целевых объекта агента:

Цель	Перейти к фигуре	Используйте, когда
Развертывание модели с привязкой к проекту	foundryprovider.ModelDeployment("gpt-4o-mini")	Ваше приложение определяет инструкции, инструменты и ход диалога.
Существующий серверный агент Foundry	foundryprovider.ServerAgent("my-agent")	Определение агента уже настроено в Foundry.

Конфигурация

Укажите конечную точку проекта Foundry и развертывание модели:

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com/api/projects/<project-id>"
FOUNDRY_MODEL="gpt-4o-mini"

агент Foundry, поддерживаемый проектом

Используйте ModelDeployment, если хотите создать в коде агент Agent Framework и передать инструкции, инструменты, промежуточное ПО и поставщиков контекста из вашего Go-приложения.

import (
    "context"
    "os"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

endpoint := os.Getenv("FOUNDRY_PROJECT_ENDPOINT")
model := os.Getenv("FOUNDRY_MODEL")

token, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    panic(err)
}

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are good at telling jokes.",
        Config: agent.Config{
            Name: "Joker",
        },
    },
)

resp, err := a.RunText(context.Background(), "Tell me a joke about a pirate.").Collect()

Существующий серверный агент Foundry

Используйте ServerAgent , когда вы хотите вызвать агент, уже настроенный в Foundry. Агент на стороне сервера владеет своими инструкциями и инструментами, поэтому AgentConfig.Instructions игнорируется для этого целевого объекта.

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ServerAgent("my-agent"),
    foundryprovider.AgentConfig{
        Config: agent.Config{
            Name: "my-agent",
        },
    },
)

resp, err := a.RunText(ctx, "Summarize the current project status.").Collect()

Tools

Агенты Foundry, поддерживаемые проектом, поддерживают стандартный интерфейс инструментов Go Agent Framework для локальных инструментов и объявлений поддерживаемых размещённых инструментов.

инструмент	Status	Примечания
Средства функций	Поддерживается	Функции выполняются в процессе Go.
Утверждение инструмента	Поддерживается	Работает с инструментами локальных функций через цикл автоматического вызова инструментов.
Интерпретатор кода	Поддерживается	Используйте &hostedtool.CodeInterpreter{}.
Поиск в Интернете	Поддерживается	Используйте &hostedtool.WebSearch{}.
Локальные средства MCP	Поддерживается	Используйте tool/mcptool, чтобы подключиться к серверу MCP и сделать его инструменты доступными локально.
Размещенные средства MCP	В настоящее время это не задокументировано для Go Foundry	Используйте локальные средства MCP, если вам нужны серверы MCP с агентами Go Foundry.
Наборы инструментов Foundry	В настоящее время это недоступно через вспомогательную функцию Go.

Для инструментов локальных функций добавьте значения tool.Tool через agent.Config.Tools:

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You are a helpful assistant.",
        Config: agent.Config{
            Tools: []tool.Tool{weatherTool},
        },
    },
)

Для выполнения размещённого кода передайте описание размещённого инструмента:

a := foundryprovider.NewAgent(
    endpoint,
    token,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "You solve problems with code.",
        Config: agent.Config{
            Tools: []tool.Tool{&hostedtool.CodeInterpreter{}},
        },
    },
)

Заголовки клиента и предоставляемая модель

Foundry принимает x-client-* заголовки для каждого запуска. Добавьте их с помощью foundryprovider.WithClientHeader или foundryprovider.WithClientHeaders:

resp, err := a.RunText(
    ctx,
    "Hello!",
    foundryprovider.WithClientHeader("x-client-scenario", "docs"),
).Collect()

Когда Foundry возвращает заголовок ответа x-ms-served-model, провайдер Go добавляет его в response/update additional properties как ServedModel.

if servedModel, ok := resp.AdditionalProperties["ServedModel"].(string); ok {
    fmt.Println(servedModel)
}

Поставщик памяти Foundry

Используйте foundryprovider.NewMemoryProvider, если нужно, чтобы агент Agent Framework при каждом запуске извлекал данные из хранилища памяти под управлением Foundry и обновлял его.

import (
    "log/slog"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

memoryProvider := foundryprovider.NewMemoryProvider(
    endpoint,
    tokenCredential,
    "memory-store-sample",
    func(*agent.Session) string { return "user-123" },
    foundryprovider.MemoryProviderConfig{
        Logger: slog.Default(),
    },
)

a := foundryprovider.NewAgent(
    endpoint,
    tokenCredential,
    foundryprovider.ModelDeployment(model),
    foundryprovider.AgentConfig{
        Instructions: "Use known memories about the user when responding.",
        Config: agent.Config{
            Name:             "FoundryMemoryAgent",
            ContextProviders: []agent.ContextProvider{memoryProvider},
        },
    },
)

Конечная точка должна быть конечной точкой Microsoft Foundry уровня проекта, а хранилище памяти уже должно существовать в этом проекте. Функция обратного вызова области видимости должна возвращать стабильный ключ секционирования для пользователя, арендатора или беседы.

Подсказка

См. образец Go для памяти Foundry для полного рабочего примера.

Текущие пробелы Go

В настоящее время поддержка Go не включает API Foundry для размещения, развертывания, управления жизненным циклом и администрирования, клиенты для эмбеддингов или вспомогательные функции Go для Foundry Toolboxes. Используйте портал Foundry или пакеты SDK сервиса для выполнения этих операций.

Дальнейшие действия

Foundry Локальный