Как поднять и управлять Microsoft Hosted Agents через Terraform: полный гид по инфраструктуре для AI-агентов — VogueTech

Что нового

Microsoft продвигает Hosted Agents в Foundry из разряда экспериментов в полноценную продакшн‑платформу. Главное изменение — теперь инфраструктуру вокруг этих агентов можно собирать и поддерживать как код с помощью Terraform.

Ключевые новшества и возможности:

Hosted Agents как управляемый рантайм: Microsoft Foundry берёт на себя запуск и масштабирование агентов. Вам не нужно поднимать Kubernetes, виртуальные машины или контейнеры.
Terraform-поддержка Foundry через AzureRM‑провайдер 4.x:
- azurerm_cognitive_account c kind = "AIServices" — верхнеуровневый аккаунт Foundry и хост для моделей.
- azurerm_cognitive_account_project — проекты Foundry, в которых живут агенты.
- azurerm_cognitive_deployment — деплой GPT‑моделей (например, gpt‑4.1 с версией 2025‑04‑14) внутри аккаунта.
Инфраструктура как код для всего окружения агента:
- Resource Group, Log Analytics Workspace, Application Insights.
- User Assigned Managed Identity и RBAC‑роли.
- Хранение Terraform‑стейта в Azure Blob Storage с блокировкой.
Поддержка продакшн‑паттернов:
- Разделение ресурсов по группам: одна под Foundry, другая под мониторинг и сеть.
- Работа с квотами Azure OpenAI и управляемыми идентичностями.

Цифры и параметры, которые важны:

Terraform: версия >= 1.9.
Azure CLI: версия >= 2.60.
AzureRM‑провайдер: ~> 4.0.
Пример деплоя модели: gpt‑4.1, версия 2025‑04‑14, SKU Standard, ёмкость 10 — это 10 000 токенов в минуту.
Время первого terraform apply: примерно 8–15 минут. Дольше всего создаётся аккаунт AIServices и деплой модели.

Фактически Microsoft даёт понятный путь: описываете инфраструктуру Hosted Agents в Terraform, применяете один план — и получаете готовую площадку для продакшн‑агентов.

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

Архитектура Foundry и Hosted Agents

Microsoft Foundry — это платформа для разработки, оценки и деплоя AI‑приложений и агентов. Hosted Agents — это агенты, которые запускаются в полностью управляемом рантайме Foundry. Вы не управляете серверами, только окружением вокруг.

Foundry строится на двух уровнях ресурсов в Azure:

Foundry Account — azurerm_cognitive_account с kind = "AIServices":
- Хостит модели (через azurerm_cognitive_deployment).
- Управляет исполнением агентов.
- Выступает логической границей для всех Foundry‑проектов.
- Обязательные параметры:
  - project_management_enabled = true — чтобы можно было создавать проекты.
  - custom_subdomain_name — глобально уникальный поддомен для доступа к сервису.
Foundry Project — azurerm_cognitive_account_project:
- Живёт внутри конкретного Foundry Account.
- В каждом проекте — свои агенты, деплои моделей, коннекции и дата‑активы.
- Обычно один проект на приложение, продуктовую команду или окружение (dev/stage/prod).

Hosted Agents работают внутри этого аккаунта и проекта. Microsoft управляет рантаймом, а вы через Terraform создаёте и связываете все сопутствующие ресурсы.

Какие ресурсы поднимает Terraform

Полноценное окружение для Hosted Agents включает:

Microsoft Foundry Account (AI Services):
- azurerm_cognitive_account с kind = "AIServices" и SKU S0.
- Внутри него — деплой модели через azurerm_cognitive_deployment (например, gpt‑4.1).
Мониторинг:
- azurerm_log_analytics_workspace — база для логов и метрик.
- azurerm_application_insights — трассировка запросов и телеметрия агентов, привязана к Log Analytics.
Безопасность и доступ:
- azurerm_user_assigned_identity — управляемая идентичность, которой Foundry будет ходить к ресурсам Azure.
- azurerm_role_assignment — выдача ролей этой идентичности:
  - Cognitive Services OpenAI User — чтобы вызывать модельные эндпоинты.
  - Cognitive Services Contributor — чтобы управлять проектами и деплоями.
- Опционально — роль Azure AI Developer вашему пользователю или сервисному аккаунту для работы с агентами.
Стейт Terraform:
- Бэкенд azurerm с хранением стейта в Azure Blob Storage.
- Используется lease‑механизм Blob Storage для блокировки стейта при terraform apply.

Поток работы

Вы настраиваете Terraform‑провайдер azurerm и бэкенд для стейта.
Описываете переменные: регион, окружение, модель, квоту TPM.
Terraform создаёт:
- Resource Group.
- Log Analytics и Application Insights.
- User Assigned Managed Identity.
- Foundry Account (AIServices) с включённым управлением проектами.
- Деплой модели (например, gpt‑4.1) внутри Foundry Account.
- Foundry Project, который использует ту же идентичность.
- RBAC‑роли для идентичности и для разработчика.
После terraform apply вы получаете:
- Идентификаторы аккаунта, проекта, деплоя модели.
- Endpoint Foundry и client_id управляемой идентичности.
Дальше через Azure AI Agent Service SDK или портал Foundry вы создаёте самих агентов: промпты, инструменты, привязка к деплою модели.

Важно: Terraform не описывает самих агентов. Он управляет инфраструктурой и доступами. Агентов создаёт ваш код или скрипты поверх этой инфраструктуры.

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

Для кого это вообще нужно

Если вы:

строите AI‑продукты на базе агентов, которые:
- ходят в внешние и внутренние API,
- читают документы,
- поднимают сложные многошаговые пайплайны;
хотите, чтобы это всё жило в Azure и масштабировалось автоматически;
устали кликать ресурсы в портале и запускать разовые скрипты,

то связка Microsoft Foundry Hosted Agents + Terraform решает сразу несколько проблем.

Практические плюсы

Повторяемые окружения:
- Один и тот же Terraform‑код создаёт dev, staging и prod.
- Staging можно сделать копией продакшна, а не «почти как прод».
- Disaster recovery — это ещё один terraform apply в другом регионе или подписке.
Управляемый рост команд и проектов:
- Каждый продукт или команда получает свой Foundry Project.
- Можно поднимать отдельные окружения «per customer» или «per team» через Terraform‑workspaces или модули.
- Все изменения инфраструктуры проходят через pull request и код‑ревью.
Прозрачное управление доступами:
- Роли Cognitive Services OpenAI User и Cognitive Services Contributor выдаются как код.
- Нет «тайных» прав, выданных руками в портале.
- Легко проверить, кто и к каким ресурсам имеет доступ.
Нормальный мониторинг из коробки:
- Логи и метрики агентов сразу летят в Log Analytics.
- Application Insights даёт трассировку запросов и ошибок.
- Это критично для продакшн‑агентов, которые живут под пользовательской нагрузкой.
Разделение ответственности:
- Платформа‑команда описывает и поддерживает Terraform‑модуль.
- Продуктовые команды создают агентов поверх уже готовой инфраструктуры.

Где это особенно полезно

Корпоративные AI‑ассистенты с доступом к внутренним системам.
Агенты для поддержки клиентов, которые ходят в CRM, биллинг и базы знаний.
Автоматизация бизнес‑процессов: многошаговые воркфлоу, где агент оркестрирует несколько систем.
Многоклиентские SaaS‑продукты, где под каждого клиента поднимается отдельный проект или даже аккаунт.

Где подход может не подойти

Небольшой прототип, который вы хотите показать за вечер.
- В этом случае проще кликнуть ресурсы в портале или вообще работать только через Foundry‑портал без Terraform.
Сценарии, где у вас нет доступа к Azure или к Foundry в конкретной подписке.
Команды, у которых нет опыта с Terraform и IaC.
- Придётся вкладываться в практики DevOps и управление стейтом.

Важные ограничения

Агенты не описываются в Terraform:
- Системный промпт, инструменты (Code Interpreter, Bing Grounding, Azure AI Search, function calling) и привязка к деплою модели создаются через SDK или портал.
- Terraform отвечает за аккаунты, проекты, деплои и доступы.
Не все типы коннекций Foundry покрыты Terraform:
- Некоторые подключения (например, Azure AI Search или кастомные коннекшены) настраиваются через Azure CLI или SDK.
Частные сети (Private Endpoint) в этом гайде не разбираются:
- Для приватного доступа нужны VNet, подсети, приватные endpoints и DNS‑зоны.
- Здесь описан путь через публичные endpoints.
Доступность в России:
- Hosted Agents и Foundry работают в Azure. Для работы нужна подписка Azure и доступ к Azure OpenAI.
- В ряде регионов и компаний доступ к Azure и Azure OpenAI ограничен. Если ваша организация блокирует Azure или требует VPN, это нужно учитывать заранее.

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

Microsoft Foundry Hosted Agents и Terraform закрывают нишу «AI‑агенты как управляемый сервис внутри Azure».

По ключевым параметрам:

Управление инфраструктурой:
- В отличие от собственного Kubernetes‑кластера или App Service, вы не управляете рантаймом агентов.
- Терраформ описывает только окружение вокруг: аккаунты, проекты, мониторинг, доступы.
Интеграция с Azure:
- Глубокая связка с Microsoft Entra ID, Azure Key Vault, Azure Blob Storage, Azure Monitor, Application Insights.
- Это естественный выбор, если ваша инфраструктура уже живёт в Azure.
Модели и квоты:
- Через azurerm_cognitive_deployment вы деплоите, например, gpt‑4.1 с версией 2025‑04‑14.
- Ёмкость задаётся в тысячах токенов в минуту, например 10 = 10 000 TPM.
- Квоты запрашиваются через Azure OpenAI Studio.
IaC‑подход:
- Terraform + AzureRM‑провайдер 4.x уже покрывают большую часть Azure‑сервисов, включая Foundry‑ресурсы.
- Для многих команд это проще, чем собственный набор скриптов на Bash/PowerShell или ARM/Bicep‑шаблоны.

Если вы уже используете Terraform для Azure, Foundry Hosted Agents логично вписываются в существующие пайплайны. Если вы живёте в другом облаке или делаете ставку на другие AI‑платформы, придётся сравнивать с их родными IaC‑подходами и смотреть, где вам удобнее жить долгосрочно.

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

Ниже — рабочий пример конфигурации из гайда Microsoft. Его можно взять как основу для своего проекта.

Требования

Учётные записи и права:

Активная подписка Azure.
Роли: Owner или Contributor + User Access Administrator на уровне подписки или ресурсной группы.
Включённый доступ к Foundry и Azure OpenAI в вашей подписке.
Квота Azure OpenAI для нужной модели (например, gpt‑4.1) — запрашивается в Azure OpenAI Studio, раздел Quotas.

Локальные инструменты:

Terraform CLI >= 1.9.
Azure CLI >= 2.60.
Редактор кода, удобно — VS Code с расширениями HashiCorp Terraform и Azure Terraform.

Аутентификация:

Для локальной разработки:

az login
az account set --subscription "<your-subscription-id>"

Для CI/CD — сервисный принципал с переменными окружения AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID или федерация через workload identity (OIDC). GitHub Actions поддерживает это нативно.

Структура проекта

Рекомендуемая структура для одного окружения:

ai-agents-infra/
├── main.tf
├── variables.tf
├── outputs.tf
├── versions.tf
└── terraform.tfvars

Если нужно переиспользование между окружениями — вынесите Foundry‑часть в модуль modules/ai-foundry/.

Настройка провайдера и бэкенда стейта

Файл versions.tf (или main.tf, если вы всё держите в одном файле):

terraform {
  required_version = ">= 1.9"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

provider "azurerm" {
  features {
    key_vault {
      purge_soft_delete_on_destroy = false
    }
    resource_group {
      prevent_deletion_if_contains_resources = true
    }
  }
  subscription_id = var.subscription_id
}

Бэкенд для стейта в Blob Storage (обычно в отдельном файле backend.tf):

terraform {
  backend "azurerm" {
    resource_group_name  = "rg-terraform-state"
    storage_account_name = "sttfstate<unique>"
    container_name       = "tfstate"
    key                  = "ai-agents/prod.tfstate"
  }
}

Ресурсы для стейта (Storage Account и контейнер) нужно создать заранее — скриптом или отдельной Terraform‑конфигурацией.

Переменные

variables.tf:

variable "subscription_id" {
  type        = string
  description = "Azure subscription ID."
}

variable "location" {
  type        = string
  default     = "eastus"
  description = "Azure region for all resources."
}

variable "environment" {
  type        = string
  default     = "dev"
  description = "Environment label (dev, staging, prod)."
}

variable "project_name" {
  type        = string
  description = "Short name for the project. Used in resource naming."
}

variable "openai_model_name" {
  type        = string
  default     = "gpt-4.1"
  description = "Azure OpenAI model to deploy for the agent."
}

variable "openai_model_version" {
  type        = string
  default     = "2025-04-14"
  description = "Model version to deploy."
}

variable "openai_sku_capacity" {
  type        = number
  default     = 10
  description = "Tokens-per-minute capacity (in thousands) for the deployment."
}

Пример terraform.tfvars (не коммитьте, если там чувствительные данные):

subscription_id      = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
location             = "eastus"
environment          = "dev"
project_name         = "contoso-agents"
openai_model_name    = "gpt-4.1"
openai_model_version = "2025-04-14"
openai_sku_capacity  = 10

Основная конфигурация: ресурсы и связи

main.tf — ядро инфраструктуры.

Локали и Resource Group

locals {
  name_prefix = "${var.project_name}-${var.environment}"
  tags = {
    environment = var.environment
    project     = var.project_name
    managed_by  = "terraform"
  }
}

resource "azurerm_resource_group" "main" {
  name     = "rg-${local.name_prefix}"
  location = var.location
  tags     = local.tags
}

Мониторинг: Log Analytics и Application Insights

data "azurerm_client_config" "current" {}

# Log Analytics Workspace (required by Application Insights)
resource "azurerm_log_analytics_workspace" "main" {
  name                = "law-${local.name_prefix}"
  resource_group_name = azurerm_resource_group.main.name
  location            = azurerm_resource_group.main.location
  sku                 = "PerGB2018"
  retention_in_days   = 30
  tags                = local.tags
}

# Application Insights for agent observability
resource "azurerm_application_insights" "main" {
  name                = "appi-${local.name_prefix}"
  resource_group_name = azurerm_resource_group.main.name
  location            = azurerm_resource_group.main.location
  workspace_id        = azurerm_log_analytics_workspace.main.id
  application_type    = "web"
  tags                = local.tags
}

Управляемая идентичность

# main.tf — Managed identity for the Microsoft Foundry Account

resource "azurerm_user_assigned_identity" "foundry" {
  name                = "id-${local.name_prefix}-foundry"
  resource_group_name = azurerm_resource_group.main.name
  location            = azurerm_resource_group.main.location
  tags                = local.tags
}

Foundry Account и деплой модели

# main.tf — Microsoft Foundry Account (AI Services)

resource "azurerm_cognitive_account" "foundry" {
  name                       = "aisa-${local.name_prefix}"
  resource_group_name        = azurerm_resource_group.main.name
  location                   = azurerm_resource_group.main.location
  kind                       = "AIServices"
  sku_name                   = "S0"
  project_management_enabled = true
  custom_subdomain_name      = "${replace(local.name_prefix, "-", "") }foundry"
  tags                       = local.tags

  identity {
    type         = "UserAssigned"
    identity_ids = [azurerm_user_assigned_identity.foundry.id]
  }
}

# Deploy the model within the Foundry Account
resource "azurerm_cognitive_deployment" "agent_model" {
  name                 = var.openai_model_name
  cognitive_account_id = azurerm_cognitive_account.foundry.id

  model {
    format  = "OpenAI"
    name    = var.openai_model_name
    version = var.openai_model_version
  }

  sku {
    name     = "Standard"
    capacity = var.openai_sku_capacity
  }
}

Обратите внимание:

custom_subdomain_name должен быть глобально уникальным. Если получите конфликт — добавьте суффикс или используйте ресурс random_string.
openai_sku_capacity задаётся в тысячах токенов в минуту. Если квоты не хватает, уменьшите значение или запросите увеличение в портале.

Foundry Project

# main.tf — Microsoft Foundry Project

resource "azurerm_cognitive_account_project" "agent_project" {
  name                 = "proj-${local.name_prefix}-agents"
  cognitive_account_id = azurerm_cognitive_account.foundry.id
  location             = azurerm_resource_group.main.location
  display_name         = "Agent Project - ${var.project_name}"
  description          = "Hosted agents project for ${var.project_name}"

  identity {
    type         = "UserAssigned"
    identity_ids = [azurerm_user_assigned_identity.foundry.id]
  }

  tags = local.tags
}

RBAC‑роли

# main.tf — RBAC assignments

# AI Services: Foundry identity needs Cognitive Services OpenAI User to call model endpoints
resource "azurerm_role_assignment" "foundry_openai" {
  scope                = azurerm_cognitive_account.foundry.id
  role_definition_name = "Cognitive Services OpenAI User"
  principal_id         = azurerm_user_assigned_identity.foundry.principal_id
}

# AI Services: Foundry identity needs Cognitive Services Contributor to manage projects
resource "azurerm_role_assignment" "foundry_contributor" {
  scope                = azurerm_cognitive_account.foundry.id
  role_definition_name = "Cognitive Services Contributor"
  principal_id         = azurerm_user_assigned_identity.foundry.principal_id
}

# Optional: grant your own principal the Azure AI Developer role on the Foundry Account
# so you can create and manage agents from your local machine or CI pipeline
resource "azurerm_role_assignment" "developer_account" {
  scope                = azurerm_cognitive_account.foundry.id
  role_definition_name = "Azure AI Developer"
  principal_id         = data.azurerm_client_config.current.object_id
}

Outputs

outputs.tf — то, что понадобятся вашим приложениям и скриптам:

output "resource_group_name" {
  value = azurerm_resource_group.main.name
}

output "foundry_account_id" {
  value = azurerm_cognitive_account.foundry.id
}

output "ai_foundry_project_id" {
  value = azurerm_cognitive_account_project.agent_project.id
}

output "foundry_endpoint" {
  value = azurerm_cognitive_account.foundry.endpoint
}

output "openai_deployment_name" {
  value = azurerm_cognitive_deployment.agent_model.name
}

output "managed_identity_client_id" {
  value = azurerm_user_assigned_identity.foundry.client_id
}

Эти значения вы будете использовать в SDK и CI/CD, когда создадите агентов и начнёте слать к ним запросы.

Деплой и проверка

Шаги деплоя:

# 1. Инициализация: скачивание провайдеров и настройка бэкенда стейта
terraform init

# 2. Проверка синтаксиса и базовой корректности
terraform validate

# 3. Просмотр плана изменений
terraform plan -out=tfplan

# 4. Применение плана
terraform apply tfplan

Первый apply занимает примерно 8–15 минут. Дольше всего создаётся аккаунт AIServices и деплой модели.

После завершения:

Проверьте ресурсную группу и ресурсы:

az resource list --resource-group "rg-contoso-agents-dev" --output table

Убедитесь, что Foundry Account в статусе Succeeded (пример команды из гайда обрывается, но проверка делается через az cognitiveservices account show).

Дальше вы можете использовать foundry_endpoint, openai_deployment_name, ai_foundry_project_id и managed_identity_client_id в коде, который создаёт и настраивает Hosted Agents через Azure AI Agent Service SDK.

Итог: Terraform берёт на себя всю инфраструктуру вокруг Microsoft Hosted Agents — от Resource Group до квот модели и RBAC. Foundry запускает и масштабирует агентов. Вы получаете воспроизводимые, управляемые и прозрачно задокументированные окружения для продакшн‑AI.