Microsoft Foundry Agent Lab: как собрать продакшн‑агента ИИ по шагам — VogueTech

Что нового

Microsoft запустила Foundry Agent Lab — открытый набор из девяти пошаговых демо для разработки AI‑агентов на Microsoft Foundry SDK.

Главные новшества и фишки:

Прогрессивный формат: 9 изолированных демо, в каждом добавляется ровно один новый концепт. От «hello world» до собственного хостинга.
Один деплоймент для всех задач: все агенты используют один и тот же деплоймент model-router, который сам выбирает модель под задачу.
Автоматический выбор модели без ручного роутинга:
- фактологический вопрос: grok-4-1-fast-reasoning;
- суммаризация диалога: gpt-5.2-chat-2025-12-11;
- запрос с инструментами (погода): gpt-5.4-mini-2026-03-17;
- генерация и выполнение кода: gpt-5.4-2026-03-05;
- RAG по HR‑документу: gpt-5.3-chat-2026-03-03.
Единый паттерн работы: во всех демо одна и та же связка:
- create_agent.py — регистрация агента;
- chat.py — диалог и обработка инструментов.
Разные типы инструментов в одном учебном наборе:
- function tools с локальным исполнением кода;
- встроенные server‑side инструменты (WebSearch, CodeInterpreter, FileSearch);
- MCP‑инструменты и Toolbox с версионированием;
- self‑hosted агент по протоколу Responses.
Полностью keyless‑подход: везде используется DefaultAzureCredential, без API‑ключей в коде.
Server‑side история диалогов: хранится в Responses API, а не в локальных списках.
Готовые сценарии:
- терминальный чат;
- десктопный UI на Tkinter;
- веб‑интерфейс на Gradio;
- self‑hosted агент в Docker, совместимый с Agent Inspector.

Это не просто пример кода, а целостный учебный маршрут: от минимального агента до продакшн‑архитектур с RAG, MCP и управлением инструментами.

Как это работает

Модельный роутер: один endpoint — много моделей

Все демо используют один деплоймент:

MODEL_DEPLOYMENT=model-router

model-router — это сервис Microsoft Foundry, который на этапе инференса анализирует запрос и отправляет его в подходящую модель. Он учитывает:

сложность задачи;
необходимость инструментов и кода;
стоимость и задержку.

Примеры реальных решений роутера из лаборатории:

вопрос: «What's the capital of WA state?» → grok-4-1-fast-reasoning (быстрый факт);
«Summarize our conversation» → gpt-5.2-chat-2025-12-11 (суммаризация);
«What's the weather in Seattle?» с инструментом погоды → gpt-5.4-mini-2026-03-17;
анализ данных с генерацией кода → gpt-5.4-2026-03-05;
вопрос по HR‑документу (RAG) → gpt-5.3-chat-2026-03-03.

Разработчик не пишет ни строчки роутинга: он просто указывает model=MODEL_DEPLOYMENT в описании агента.

Demo 0: минимальный агент на Responses API

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

Регистрация агента

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

credential = DefaultAzureCredential()
project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=credential)

agent = project.agents.create_version(
    agent_name=AGENT_NAME,
    definition=PromptAgentDefinition(
        model=MODEL_DEPLOYMENT,
        instructions="You are a helpful, friendly assistant.",
    ),
)

Здесь важно:

авторизация через DefaultAzureCredential — локально работает через az login, в проде через managed identity;
ни одного API‑ключа в коде.

Диалог с агентом через Responses API

# Create a server-side conversation (persists history across turns)
conversation = openai.conversations.create()

# Each turn sends the user message; the agent sees full history
response = openai.responses.create(
    input=user_input,
    conversation=conversation.id,
    extra_body={"agent_reference": {"name": AGENT_NAME, "type": "agent_reference"}},
)
print(response.output_text)

История хранится на стороне Foundry, вы передаёте только conversation.id. Это другой паттерн по сравнению с классическими Completions/Chat Completions.

Demo 1: function tools и цикл вызова инструментов

Здесь появляется реальный инструмент — API погоды. Модель не выполняет функцию сама, она лишь запрашивает вызов.

Объявление инструмента

from azure.ai.projects.models import FunctionTool, PromptAgentDefinition

func_tool = FunctionTool(
    name="get_weather",
    description="Get the current weather for a given city.",
    parameters={
        "type": "object",
        "properties": {"city": {"type": "string", "description": "City name"}},
        "required": ["city"],
    },
    strict=True,
)

agent = project.agents.create_version(
    agent_name=AGENT_NAME,
    definition=PromptAgentDefinition(
        model=MODEL_DEPLOYMENT,
        tools=[func_tool],
        instructions="You are a weather assistant...",
    ),
)

strict=True заставляет модель возвращать аргументы строго по JSON‑схеме. Это уменьшает количество ошибок парсинга в продакшене.

Цикл вызова инструментов

response = openai.responses.create(input=user_input, conversation=conversation.id, ...)

# Loop while the model is requesting tool calls
while any(item.type == "function_call" for item in response.output):
    input_list = []
    for item in response.output:
        if item.type == "function_call":
            args = json.loads(item.arguments)
            result = get_weather(args["city"])   # execute locally
            input_list.append(FunctionCallOutput(call_id=item.call_id, output=result))
    # Send results back to the agent
    response = openai.responses.create(input=input_list, conversation=conversation.id, ...)

print(response.output_text)

Логика такая:

Модель отвечает не текстом, а запросом function_call с аргументами.
Ваш код вызывает реальный API (get_weather) и формирует FunctionCallOutput.
Результаты отправляются обратно в responses.create, модель формирует финальный ответ.

Demo 2: UI отдельно, агент отдельно

Второе демо использует того же агента, что и Demo 1, но вместо терминала — UI на Tkinter. Агент, инструменты и цикл вызова остаются прежними.

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

Demo 3: встроенный WebSearchTool без клиентского цикла

WebSearchTool выполняется внутри Foundry, поэтому клиентский цикл для инструментов исчезает.

from azure.ai.projects.models import WebSearchTool

agent = project.agents.create_version(
    agent_name="Search-Agent",
    definition=PromptAgentDefinition(
        model=MODEL_DEPLOYMENT,
        tools=[WebSearchTool()],
        instructions="You are a research assistant...",
    ),
)

Агент сам решает, когда искать, выполняет поиск на стороне Foundry и возвращает ответ с источниками. Клиентский код такой же, как в Demo 0 — обычный responses.create().

Разделение получается таким:

Function tools (Demo 1) — исполнение у вас, вы управляете кодом, API, ошибками.
Built‑in tools (Demo 3+) — исполнение в Foundry, вы получаете только результат.

Demo 4: CodeInterpreterTool и веб‑UI на Gradio

CodeInterpreterTool даёт агенту песочницу Python внутри Foundry:

агент пишет код;
запускает его в изолированной среде;
читает вывод и может дорабатывать решение.

В демо это объединено с веб‑интерфейсом на Gradio: пользователь загружает данные, агент строит графики, считает метрики и объясняет результат прямо в браузере.

Model Router в этом сценарии чаще выбирает более мощную модель gpt-5.4-2026-03-05 для задач с кодом, а обычные реплики остаются на более лёгких моделях.

Demo 5: RAG через FileSearchTool

Пятое демо показывает полный цикл Retrieval‑Augmented Generation.

Подготовка: загрузка документа и векторное хранилище

# Upload document and create a vector store
vector_store = openai.vector_stores.create(name="employee-handbook-store")
with open("data/employee-handbook.md", "rb") as f:
    openai.vector_stores.files.upload_and_poll(
        vector_store_id=vector_store.id, file=f
    )

# Attach the vector store to the agent
agent = project.agents.create_version(
    agent_name="RAG-Agent",
    definition=PromptAgentDefinition(
        model=MODEL_DEPLOYMENT,
        tools=[FileSearchTool(vector_store_ids=[vector_store.id])],
        instructions="Answer questions using only the provided documents...",
    ),
)

Ключевые детали:

создаётся vector_store и туда загружается employee-handbook.md;
ID векторного хранилища сохраняется в файл .vector_store_id и читается при старте, чтобы не загружать документ заново при каждом запуске;
этот файл добавлен в .gitignore.

Запрос: агент сам эмбеддит вопрос, ищет релевантные куски в vector store, подмешивает их в контекст и генерирует ответ, опираясь только на эти документы. Весь пайплайн работает на стороне Foundry, клиент по‑прежнему делает один responses.create().

Demo 6: Model Context Protocol и human‑in‑the‑loop

Шестое демо подключает GitHub MCP‑сервер. MCP (Model Context Protocol) — это стандартный протокол, через который агенты получают доступ к внешним инструментам.

Особенности:

инструменты описаны и живут в отдельном MCP‑сервере (здесь GitHub репозитории и issues);
агент сам обнаруживает доступные инструменты через протокол, без объявлений FunctionTool на клиенте;
перед каждым вызовом MCP‑инструмента агент показывает пользователю, что собирается сделать, и ждёт подтверждения.

Это демонстрация важного паттерна безопасности: всё, что может менять внешнее состояние (создавать issue, писать в репозиторий, слать письма), должно идти через явное подтверждение пользователя.

Demo 7: Toolbox — версия инструментов как ресурс

Toolbox — управляемый ресурс в Microsoft Foundry, который объединяет несколько инструментов в один MCP‑совместимый endpoint.

В демо Toolbox содержит:

инструменты GitHub Issues;
инструменты GitHub Repos;
зафиксированную версию набора инструментов.

Подключение в коде:

from azure.ai.projects.models import McpTool

toolbox_tool = McpTool(
    server_label="toolbox",
    server_url=TOOLBOX_ENDPOINT,
    allowed_tools=[],   # empty = all tools in the Toolbox version
    headers={"Authorization": f"Bearer {token}"},
)

Особенности подхода:

один endpoint для множества инструментов;
снапшоты по версиям: агент явно привязан к версии Toolbox и обновляется только по решению команды;
MCP‑совместимость: любой агент, который умеет в MCP, может использовать Toolbox, не только агенты на Foundry SDK.

Demo 8: self‑hosted агент по протоколу Responses

Финальное демо уходит от декларативного PromptAgentDefinition. Вместо этого вы поднимаете собственный HTTP‑сервер, который реализует протокол Responses.

Особенности:

сервер отдаёт стриминговые ответы на запросы Foundry;
Agent Inspector в Foundry может подключаться к этому серверу так же, как к обычному hosted‑агенту;
деплой через Dockerfile и agent.yaml на контейнерный хостинг Foundry;
внутри сервера используется gpt-4.1-mini напрямую, без model-router — вы полностью контролируете инференс.

Когда это оправдано:

нужны нестандартные препроцессинг/постпроцессинг, которые нельзя выразить системным промптом;
интеграция с инфраструктурой, недоступной через MCP или встроенные инструменты;
контроль затрат, A/B‑тесты, выполнение требований комплаенса к инференсу;
вы строите оркестратор из нескольких агентов и хотите выставить его наружу как ещё одного агента.

Что это значит для вас

Для кого полезен Foundry Agent Lab

Backend‑разработчики и ML‑инженеры, которые хотят быстро собрать продакшн‑агента без погружения в десятки фреймворков.
Команды, уже использующие Azure, — тут хорошо ложится авторизация через DefaultAzureCredential и managed identity.
Архитекторы, которые проектируют многоагентные системы с RAG, инструментами и строгими требованиями по безопасности.

Где это реально помогает

Быстрый старт с агентами без “адской” связки SDK и сервисов
- Начинаете с Demo 0 — минимальный агент.
- Добавляете инструменты, UI, RAG, MCP по мере необходимости.
- Каждое следующее демо меняет одну вещь, поэтому легко понять, что за что отвечает.
Продакшн‑агенты с инструментами и RAG
- Function tools (Demo 1) — для интеграций с внутренними API, где важен полный контроль и логирование.
- FileSearchTool (Demo 5) — для корпоративных баз знаний: HR‑политики, регламенты, документация.
- MCP + Toolbox (Demo 6–7) — для доступа к GitHub, CRM, тикет‑системам через единый управляемый слой.
Системы с жёсткими требованиями безопасности
- Human‑in‑the‑loop перед вызовом MCP‑инструментов.
- Явное ограничение allowed_tools в Toolbox.
- Отсутствие API‑ключей в коде, авторизация через managed identity в проде.
Эксперименты с архитектурой агентов
- Сравнение client‑side и server‑side инструментов на одном стеке.
- Переход от hosted‑агента к self‑hosted (Demo 8), когда нужно полностью контролировать инференс.

Где продукт не поможет

Если вы не используете Azure и Microsoft Foundry, пересадка инфраструктуры ради этого набора демо вряд ли оправдана.
Если вам нужен только «один чат‑бот на сайте», без инструментов и RAG, Foundry Agent Lab будет избыточен — проще взять готовый SaaS‑чат.
Если вы не можете использовать сервисы Microsoft из‑за ограничений доступа или комплаенса, этот стек не закроет ваши задачи.

Вопрос доступности из России

Foundry Agent Lab требует:

Azure‑подписку;
доступ к Microsoft Foundry в Azure;
работу с endpoint вида https://your-resource.ai.azure.com/api/projects/your-project.

В российских сетях доступ к Azure и связанным AI‑сервисам часто ограничен. На практике для работы может потребоваться VPN и юридическая возможность использовать зарубежные облака. Это нужно проверять отдельно в вашей организации.

Место на рынке

Foundry Agent Lab — это не модель, а учебный и референсный набор для построения агентов вокруг моделей Microsoft, включая gpt-5.2-chat-2025-12-11, gpt-5.3-chat-2026-03-03, gpt-5.4-2026-03-05 и gpt-4.1-mini.

Сравнение с другими экосистемами корректно делать по типам возможностей:

Автовыбор модели через model router
- Похожую идею реализуют роутеры в других платформах, но здесь она встроена в Microsoft Foundry и завязана на один деплоймент.
- В демо видно, что роутер сам выбирает разные модели под фактологию, суммаризацию, код, RAG.
Работа с инструментами
- Function tools напоминают function calling в OpenAI, но здесь они интегрированы в Foundry SDK и Responses API.
- Built‑in инструменты (WebSearch, CodeInterpreter, FileSearch) снимают с разработчика задачу хостинга и масштабирования этих сервисов.
MCP и Toolbox
- MCP набирает популярность как стандарт для подключения внешних ресурсов к агентам.
- Toolbox добавляет управляемый слой поверх MCP: версии, централизованное владение инструментами, явное разрешение на их использование.
Self‑hosted по Responses protocol
- Это альтернатива «чистому» REST‑инференсу: вы реализуете протокол, и Foundry обращается к вашему серверу как к нативному агенту.

Конкретных цифр по скорости, задержке или стоимости запросов в лаборатории нет. Но по набору покрытых сценариев (RAG, инструменты, код, MCP, self‑hosted) это полноценный референс для архитектуры агентных систем на Microsoft Foundry.

Установка

Лаборатория написана на Python и требует:

Python 3.10+;
Azure‑подписку с проектом Microsoft Foundry;
установленный Azure CLI.

Клонирование репозитория и виртуальное окружение

git clone https://github.com/microsoft-foundry/Foundry-Agent-Lab.git
cd Foundry-Agent-Lab

# Create and activate the virtual environment
python -m venv .venv

# Windows Command Prompt
.venv\Scripts\activate.bat

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

Как запустить

1. Настройка демо

Скопируйте файл окружения для первого демо:

copy hello-demo\.env.sample hello-demo\.env

Отредактируйте hello-demo\.env и задайте PROJECT_ENDPOINT.

PROJECT_ENDPOINT можно взять на странице Overview вашего Foundry‑проекта в Azure Portal. Формат:

https://your-resource.ai.azure.com/api/projects/your-project

2. Аутентификация и запуск первого демо

az login
0-hello-demo

Каждый нумерованный .bat в корне:

активирует виртуальное окружение;
запускает create_agent.py;
запускает chat.py.

Чтобы сохранить лог сессии:

0-hello-demo log

3. Сброс между запусками

hello-demo\reset.bat

Каждое демо содержит reset.bat, который удаляет зарегистрированного агента и связанные ресурсы (vector stores, загруженные файлы). Это делает эксперименты повторяемыми.

Архитектурные принципы

Лаборатория последовательно показывает несколько практик, которые полезны в продакшене:

Keyless‑аутентификация
- Везде используется DefaultAzureCredential.
- Локально учётка подтягивается из az login.
- В проде тот же код автоматически переходит на managed identity, без хранения секретов.
История диалогов на сервере
- Responses API хранит всю историю.
- Приложение оперирует только conversation.id.
- Это упрощает масштабирование на несколько процессов и инстансов.
Граница между client‑side и server‑side инструментами
- Function tools — ваш код, ваш контроль, ваши логи.
- WebSearch, CodeInterpreter, FileSearch — вся тяжёлая работа в Foundry.
- MCP‑инструменты и Toolbox — отдельные сервисы, к которым Foundry обращается по протоколу.
Разделение регистрации агента и диалога
- create_agent.py отвечает за описание и регистрацию агента.
- chat.py отвечает за диалог и обработку инструментов.
- Можно менять инструкцию и набор инструментов, не трогая клиентский код, и наоборот.

Безопасность

При переносе паттернов из лаборатории в продакшн стоит учитывать:

Не коммитьте .env
- Они уже в .gitignore, но лучше перепроверить.
- Для продакшна используйте Azure Key Vault или переменные окружения в CI/CD.
Используйте managed identity в Azure
- DefaultAzureCredential автоматически переключится на неё.
- Не нужно хранить ключи и токены в хранилищах.
Human‑in‑the‑loop для инструментов с побочными эффектами
- Demo 6 показывает подтверждение MCP‑вызовов.
- Любой агент, который может создавать задачи, отправлять письма или менять данные, должен показывать план действий пользователю.
Проверяйте результаты инструментов
- Данные из внешних API, поиска и RAG нужно считать недоверенными.
- Prompt‑инъекции через содержимое документов и поисковой выдачи — реальный риск.
Ограничивайте Toolbox
- Используйте allowed_tools, а не доступ ко всем инструментам сразу.
- Это снижает риск неконтролируемых действий агента.

Что попробовать дальше

Репозиторий: github.com/microsoft-foundry/Foundry-Agent-Lab.
Документация по Microsoft Foundry SDK: learn.microsoft.com/azure/ai-studio/.
Быстрый старт по Responses API и prompt‑агентам — в документации Foundry.
Описание Model Router: раздел о Model Router для Microsoft Foundry.
Стандарт Model Context Protocol: modelcontextprotocol.io.
Документация Azure Identity (DefaultAzureCredential): пакет azure-identity для Python.

Foundry Agent Lab распространяется под лицензией MIT. В репозитории открыты issues для багрепортов и фич‑запросов, есть CONTRIBUTING.md с правилами участия.