Хосты возможностей

Узлы функциональности — это подресурсы, настроенные как в рамках учетной записи Microsoft Foundry, так и в рамках проектов Foundry. Они сообщают Службе агентов Foundry, где хранить и обрабатывать данные агента, в том числе:

• История беседы
• Отправка файлов
• Хранилища векторов

Необходимые условия

• Проект Microsoft Foundry
• Если вы используете собственные ресурсы для данных агента (стандартная настройка агента), создайте необходимые Azure ресурсы и подключения:
  • Использование собственных ресурсов
  • Добавление нового подключения к проекту
• Необходимые разрешения:
  • Роль вкладчика в учетной записи Foundry для создания хостов возможностей
  • Администратор доступа пользователя или роль «Owner» для назначения доступа к ресурсам Azure (для стандартной настройки агента)
  • Дополнительные сведения см. в разделе Необходимые разрешения и Управление доступом на основе ролей (RBAC) в Microsoft Foundry.

Зачем использовать узлы возможностей?

Узлы возможностей позволяют вам использовать собственные ресурсы Azure вместо использования ресурсов платформы, которые по умолчанию управляет Microsoft. Это дает вам следующее:

• Data sovereignty — храните все данные агента в подписке Azure.
• Управление безопасностью . Используйте собственные учетные записи хранения, базы данных и службы поиска.
• Соответствие требованиям. Соответствует определенным нормативным или организационным требованиям.

Как работают хосты возможностей?

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

Поведение по умолчанию (управляемые Microsoft ресурсы)

Если узлы возможностей не создаются, служба агента автоматически использует ресурсы, управляемые Microsoft Azure:

• Хранилище разговоров (история разговоров, определения агентов)
• Хранилище файлов (отправленные документы)
• Векторный поиск (внедрение и извлечение)

Использование собственных ресурсов

При создании узлов возможностей как на уровне учетной записи, так и на уровне проекта, ресурсы Azure хранят и обрабатывают данные агентов. Это стандартная настройка агента. Сведения о защите службы агента см. в разделе "Настройка частной сети для службы агента Foundry".

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

Иерархия конфигурации

Функциональные хосты работают в двух отдельных областях действия:

1. Настройки службы по умолчанию (поиск и хранилище, управляемые Microsoft) — используется, когда узел функций не настроен.
2. Хост компонента на уровне учетной записи — включает службу агента на уровне учетной записи.
3. Узел возможностей уровня проекта — определяет, какие ресурсы BYO использует Agent Service для этого конкретного проекта.

Понимание ограничений хоста возможностей

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

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

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

• Предварительные требования к узлу возможностей учетной записи: невозможно создать узел возможностей проекта, если узел возможностей уровня учетной записи еще не существует.

Установка подключений для функциональных хостов

Возможности содержат ссылки на имена подключений, создаваемые в учетной записи и проекте Foundry. Перед настройкой узла возможностей проекта для стандартной настройки агента создайте подключения для ресурсов, которые хранят данные агента:

• Хранилище бесед: подключение Azure Cosmos DB
• File storage: подключение служба хранилища Azure
• Vector store: подключение к Поиск с использованием ИИ Azure

Если вы хотите использовать развертывания моделей из собственного ресурса Azure OpenAI, также создайте подключение Azure OpenAI.

Сведения о добавлении подключений на портале Foundry см. в статье "Добавление нового подключения к проекту".

Обязательные свойства подключения

Чтобы служба Agent Service могла правильно разрешать и использовать ваши ресурсы во время выполнения, каждое подключение, на которое ссылается узел возможностей, должно иметь заполненные следующие свойства:

В следующем примере показано правильно настроенное подключение служба хранилища Azure:

{
  "properties": {
    "authType": "AAD",
    "category": "AzureStorageAccount",
    "target": "https://{storageAccountName}.blob.core.windows.net/",
    "metadata": {
      "ResourceId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}"
    }
  }
}

Настройка хостов возможностей

В настоящее время вы управляете узлами возможностей с помощью REST API. Поддержка пакета SDK для управления возможностями узла недоступна.

Обязательные свойства (хост возможности проекта)

Чтобы использовать собственные ресурсы для данных агента (стандартная настройка агента), настройте возможности узла проекта со следующими свойствами:

Необязательное свойство

Хост возможностей учетной записи

Используйте хост возможностей аккаунта, чтобы включить Agent Service на уровне аккаунта.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents"
  }
}

Справка: REST API управления учетными записями Foundry

сервер возможностей проекта

Хост возможностей проекта — это сущность, которую служба Agent Service считывает, чтобы определить, какие ресурсы BYO следует использовать в проекте. Все агенты в этом проекте будут использовать ресурсы, указанные здесь:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["my-cosmos-db-connection"],
    "vectorStoreConnections": ["my-ai-search-connection"],
    "storageConnections": ["my-storage-account-connection"],
    "aiServicesConnections": ["my-azure-openai-connection"]
  }
}

Справочник: Узлы возможностей проекта — создать или обновить

Необязательно. Подключения на уровне учетной записи с узлами возможностей проекта

Вы также можете определить подключения на уровне учетной записи. При создании нового проекта в этой учетной записи эти подключения наследуются проектом. Однако конфигурация хоста возможностей проекта не наследуется — вам всё равно необходимо явно создать хост возможностей проекта и указать подключения, которые Agent Service должен использовать для этого проекта.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["shared-cosmosdb-connection"],
    "vectorStoreConnections": ["shared-ai-search-connection"],
    "storageConnections": ["shared-storage-connection"]
  }
}

Проверка конфигурации

Выполните следующие действия, чтобы убедиться, что узлы возможностей настроены правильно:

1. Получите хост возможностей учетной записи и подтвердите его наличие.

   GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts?api-version=2025-06-01
   

2. Получите хост возможностей проекта и подтвердите, что он содержит ссылки на ожидаемые имена подключений.

   GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts?api-version=2025-06-01
   

3. Проверьте конфигурацию, создав агент тестирования и выполнив беседу. Убедитесь, что:

   • Беседы отображаются в Azure Cosmos DB.
   • Загруженные файлы отображаются в учетной записи служба хранилища Azure
   • Векторные данные отображаются в индексе Поиск с использованием ИИ Azure

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

Удаление хостов возможностей

Удалить хост возможностей уровня учетной записи

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

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

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

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

Если при создании узлов возможностей возникают проблемы, в этом разделе приводятся решения наиболее распространенных проблем и ошибок.

Ошибки конфликта HTTP 409

Проблема: несколько хостов возможностей в области

Симптомы: При попытке создать хост возможностей возникает ошибка 409 (Конфликт), даже если вы полагаете, что область применения пуста.

Сообщение об ошибке:

{
  "error": {
    "code": "Conflict",
    "message": "There is an existing Capability Host with name: existing-host, provisioning state: Succeeded for workspace: /subscriptions/.../workspaces/my-workspace, cannot create a new Capability Host with name: new-host for the same ClientId."
  }
}

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

Решение:

1. Проверка существующих узлов возможностей — запрос области, чтобы просмотреть уже существующие узлы возможностей.
2. Использование согласованного именования . Убедитесь, что вы используете одно и то же имя для всех запросов для одной области.
3. Проверьте требования - Определите, соответствует ли существующий хост возможностей вашим потребностям.

Шаги проверки: Используйте запросы GET в разделе "Проверка конфигурации" , чтобы убедиться, что узел возможностей уже существует в целевой области.

Проблема. Выполнение параллельных операций

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

Сообщение об ошибке:

{
  "error": {
    "code": "Conflict", 
    "message": "Create: Capability Host my-host is currently in non creating, retry after its complete: /subscriptions/.../workspaces/my-workspace"
  }
}

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

Решение:

1. Дождитесь завершения текущей операции . Проверьте состояние текущих операций
2. Мониторинг хода выполнения операции . Использование API операций для отслеживания завершения
3. Используйте логику повторных попыток — применяйте экспоненциальный откат для временных конфликтов

Мониторинг операций:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/locations/{location}/operationResults/{operationId}?api-version=2025-06-01

Рекомендации по предотвращению конфликтов

1. Предварительная проверка запроса

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

• Запрос существующих узлов возможностей в целевой области
• Проверка текущих операций
• Общие сведения о текущей конфигурации

2. Реализуйте логику повторных попыток с экспоненциальной задержкой

try 
{
    var response = await CreateCapabilityHostAsync(request);
    return response;
}
catch (HttpRequestException ex) when (ex.Message.Contains("409"))
{
    if (ex.Message.Contains("existing Capability Host with name"))
    {
        // Handle name conflict - check if existing resource is acceptable
        var existing = await GetExistingCapabilityHostAsync();
        if (IsAcceptable(existing))
        {
            return existing; // Use existing resource
        }
        else
        {
            throw new InvalidOperationException("Scope already has a capability host with different name");
        }
    }
    else if (ex.Message.Contains("currently in non creating"))
    {
        // Handle concurrent operation - implement retry with backoff
        await Task.Delay(TimeSpan.FromSeconds(30));
        return await CreateCapabilityHostAsync(request); // Retry once
    }
}

3. Разобраться в идемпотентном поведении

Система поддерживает идемпотентные запросы на создание:

• То же имя и та же конфигурация → Возвращает существующий ресурс (200 ОК)
• То же имя + другая конфигурация → возвращает 400 недопустимых запросов
• Другое имя → возвращает конфликт 409

4. Рабочий процесс изменения конфигурации

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

1. Удалите существующий хост возможностей
2. Дождитесь завершения удаления
3. Создание нового узла возможностей с требуемой конфигурацией

Распространенные сценарии

• Разработка и тестирование: используйте ресурсы, управляемые Microsoft. Конфигурация хоста возможностей не требуется.
• Производство с требованиями соответствия: Создайте хосты возможностей с использованием собственных Azure Cosmos DB, хранилища и поиска на базе ИИ.
• Общие ресурсы для всех проектов: настройте подключения на уровне учетной записи, затем создайте для каждого проекта хост возможностей проекта, явно ссылающийся на эти подключения.

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

• Настройка стандартного агента
• Настройка среды
• Добавление нового подключения к проекту