Hosts de capacidad

Los hosts de capacidad son subrecursos que se configuran en los ámbitos de la cuenta de Microsoft Foundry y los proyectos de Foundry. Indican al servicio de agente de Foundry dónde almacenar y procesar los datos del agente, entre los que se incluyen:

• Historial de conversaciones
• Cargas de archivos
• Almacenes de vectores

Requisitos previos

• Un proyecto Microsoft Foundry
• Si usa sus propios recursos para los datos del agente (configuración estándar del agente), cree los recursos y conexiones necesarios Azure:
  • Utilice sus propios recursos
  • Agregar una nueva conexión al proyecto
• Permisos necesarios:
  • Rol de Colaborador en la cuenta de Foundry para crear hosts de funcionalidad
  • Rol de Administrador de acceso de usuario o Propietario para asignar acceso a recursos de Azure (para la configuración del agente estándar)
  • Para obtener más información, consulte Permisos requeridos y Control de acceso basado en roles (RBAC) en Microsoft Foundry.

¿Por qué usar hosts de capacidad?

Los hosts de funcionalidad permiten aportar sus propios recursos de Azure en lugar de utilizar los recursos predeterminados de la plataforma administrados por Microsoft. Esto le proporciona lo siguiente:

• Soberanía de los datos: mantenga todos los datos del agente dentro de su suscripción de Azure.
• Control de seguridad : use sus propias cuentas de almacenamiento, bases de datos y servicios de búsqueda.
• Cumplimiento: cumple requisitos normativos o organizativos específicos.

¿Cómo funcionan los anfitriones de capacidad?

No es necesario crear hosts de capacidad. Si desea que los agentes usen sus propios recursos de Azure, cree anfitriones de capacidad en los ámbitos de cuenta y proyecto.

Comportamiento predeterminado (recursos administrados Microsoft)

Si no crea anfitriones de capacidad, el servicio del agente usa automáticamente recursos de Azure administrados por Microsoft para:

• Almacenamiento de conversaciones (historial de conversaciones, definiciones de agente)
• Almacenamiento de archivos (documentos cargados)
• Búsqueda de vectores (incrustaciones y recuperación)

Traiga sus propios recursos

Al crear hosts de capacidad en los niveles de cuenta y proyecto, los recursos de Azure almacenan y procesan los datos del agente. Esta es la configuración estándar del agente. Para proteger su servicio de agente, consulte Configurar redes privadas para Foundry Agent Service.

Para más información sobre la configuración del agente estándar, consulte Preparación empresarial integrada con la configuración del agente estándar.

Jerarquía de configuración

Los hosts de capacidad operan en dos niveles distintos:

1. Service - valores predeterminados (búsqueda y almacenamiento administrados por Microsoft): se usa cuando no hay ningún host de capacidades configurado.
2. Alojamiento de capacidad a nivel de cuenta - Habilita el servicio del agente en el nivel de cuenta.
3. Host de funcionalidades a nivel de proyecto - Define qué recursos BYO usa el servicio del agente para ese proyecto específico.

Comprender las restricciones del host de funcionalidad

Al crear hosts de funcionalidad, tenga en cuenta estas restricciones importantes para evitar conflictos:

• Un host de funcionalidad por ámbito: cada cuenta y cada proyecto solo puede tener un host de funcionalidad activo. Si intenta crear un segundo host de funcionalidad con un nombre diferente en el mismo ámbito, recibirá un error 409.

• No se pueden actualizar las configuraciones: si necesita cambiar la configuración, elimine el host de funcionalidad existente y vuelva a crearlo.

• Requisito previo del host de capacidades de la cuenta: no se puede crear un host de capacidades del proyecto a menos que ya exista un host de capacidades en el nivel de cuenta.

Creación de conexiones para hosts de capacidad

La funcionalidad hospeda nombres de conexión de referencia que se crean en la cuenta y el proyecto de Foundry. Antes de configurar un host de funcionalidad del proyecto para la configuración del agente estándar, cree conexiones para los recursos que almacenan los datos del agente:

• Almacenamiento de conversaciones: conexión de Azure Cosmos DB
• File storage: conexión de Azure Storage
• Vector store: conexión de Búsqueda de Azure AI

Si quiere usar implementaciones de modelos desde su propio recurso de OpenAI de Azure, cree también una conexión de OpenAI Azure.

Para agregar conexiones en el portal de Foundry, consulte Incorporación de una nueva conexión al proyecto.

Propiedades de conexión necesarias

Para que el servicio del agente resuelva y use correctamente los recursos en tiempo de ejecución, cada conexión a la que hace referencia un host de funcionalidad debe tener rellenadas las siguientes propiedades:

En el ejemplo siguiente se muestra una conexión Azure Storage configurada correctamente:

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

Configuración de hosts de capacidad

Actualmente, administra los hosts de funcionalidad mediante la API de REST. La compatibilidad del SDK con la gestión de hosts de capacidades no está disponible.

Propiedades necesarias (host de funcionalidad del proyecto)

Para usar sus propios recursos para los datos del agente (configuración estándar del agente), configure el host de funcionalidad del proyecto con las siguientes propiedades:

Propiedad opcional

Host de funcionalidad de la cuenta

Use un host de funcionalidad de cuenta para habilitar el servicio del agente en el nivel de cuenta.

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

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

Referencia: API REST de administración de cuentas de Foundry

Host de capacidad del proyecto

El host de capacidades del proyecto es lo que el servicio del agente lee para determinar qué recursos BYO usar en un proyecto. Todos los agentes de este proyecto usarán los recursos a los que se hace referencia aquí:

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"]
  }
}

Referencia: Anfitriones de capacidades de proyecto - Crear o actualizar

Opcional: conexiones a nivel de cuenta con hosts con capacidad de proyecto

También puede definir conexiones en el nivel de cuenta. Cuando se crea un nuevo proyecto en esa cuenta, el proyecto hereda esas conexiones. Sin embargo, la configuración del host de capacidades del proyecto no se hereda; debe seguir creando explícitamente un host de capacidades del proyecto y hacer referencia a las conexiones que desea que utilice Agent Service para ese proyecto.

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"]
  }
}

Comprobación de la configuración

Siga estos pasos para confirmar que los hosts de funcionalidad están configurados correctamente:

1. Obtenga el host de capacidad de la cuenta y confirme que existe.

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

2. Obtenga el host de capacidad del proyecto y confirme que hace referencia a los nombres de conexión esperados.

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

3. Pruebe la configuración mediante la creación de un agente de prueba y la ejecución de una conversación. Confirme que:

   • Las conversaciones aparecen en el Azure Cosmos DB.
   • Los archivos cargados aparecen en la cuenta de Azure Storage
   • Los datos vectoriales aparecen en el índice de Búsqueda de Azure AI

4. Si actualiza las conexiones o desea cambiar dónde se almacenan los datos, elimine y vuelva a crear los hosts de funcionalidad con la configuración actualizada.

Eliminación de hosts de funcionalidad

Eliminación de un host de funcionalidad de nivel de cuenta

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

Eliminar un host de capacidad a nivel de proyecto

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

Solución de problemas

Si experimenta problemas al crear hosts de capacidad, esta sección proporciona soluciones a los problemas y errores más comunes.

Errores de conflicto HTTP 409

Problema: múltiples hosts de capacidad por ámbito

Síntomas: se recibe un error de conflicto 409 al intentar crear un host de funcionalidad, aunque cree que el ámbito está vacío.

Mensaje de error:

{
  "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."
  }
}

Causa principal: Cada cuenta y cada proyecto solo pueden tener un host de funcionalidad activo. Está intentando crear un host de funcionalidad con un nombre diferente cuando ya existe uno en el mismo ámbito.

Solución:

1. Verifique los hosts de funcionalidad existentes: consulte el ámbito para ver qué existe.
2. Usar nomenclatura coherente : asegúrese de que usa el mismo nombre en todas las solicitudes para el mismo ámbito.
3. Revisión de los requisitos : determine si el host de funcionalidad existente satisface sus necesidades.

Pasos de validación: Use las solicitudes GET en Comprobar la configuración para confirmar si ya existe un host de funcionalidad en el ámbito de destino.

Problema: Operaciones simultáneas en curso

Síntomas: Recibe un error de conflicto 409 que indica que se está ejecutando otra operación actualmente.

Mensaje de error:

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

Causa principal: Está intentando crear un host de funcionalidad mientras que otra operación (actualización, eliminación, modificación) está en curso en el mismo ámbito.

Solución:

1. Espere a que se complete la operación actual : compruebe el estado de las operaciones en curso.
2. Supervisión del progreso de la operación: uso de la API de operaciones para realizar un seguimiento de la finalización
3. Implementación de la lógica de reintento : uso del retroceso exponencial para conflictos temporales

Supervisión de operaciones:

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

Procedimientos recomendados para la prevención de conflictos

1. Validación previa de la solicitud

Compruebe siempre el estado actual antes de realizar cambios:

• Consultar hosts de funcionalidad existentes en el ámbito de destino
• Comprobación de las operaciones en curso
• Descripción de la configuración actual

2. Implementación de la lógica de reintento con retroceso exponencial

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. Comprender el comportamiento idempotente

El sistema admite solicitudes de creación idempotentes:

• El mismo nombre y la misma configuración → Devuelve el recurso existente (200 Ok)
• Mismo nombre + configuración diferente → Devuelve 400 solicitud incorrecta
• Nombre diferente → Devuelve 409 Conflicto

4. Flujo de trabajo de cambio de configuración

Dado que no se admiten las actualizaciones, siga esta secuencia para ver los cambios de configuración:

1. Eliminación del host de funcionalidad existente
2. Espere a que se complete la eliminación
3. Creación de un nuevo host de funcionalidad con la configuración deseada

Escenarios comunes

• Desarrollo y pruebas: Use recursos administrados por Microsoft. No se necesita ninguna configuración de host de capacidad.
• Producción con requisitos de cumplimiento: cree hosts de capacidad con su propia instancia de Azure Cosmos DB, almacenamiento y AI Search.
• Recursos compartidos entre proyectos: configure conexiones de nivel de cuenta y cree un host de funcionalidad de proyecto para cada proyecto que haga referencia explícitamente a esas conexiones.

Pasos siguientes

• Configuración del agente estándar
• Configuración del entorno
• Agregar una nueva conexión al proyecto