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 (subprocesos)
• 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
  • Administrador de acceso de usuario o Propietario para asignar acceso a recursos de Azure (para la configuración estándar del agente)
  • Para obtener más información, consulte los permisos requeridos y el 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 la 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 hosts de capacidad?

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

Comportamiento predeterminado (recursos administrados Microsoft)

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

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

Traiga sus propios recursos

Al crear anfitriones 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 la configuración del agente estándar protegido por red, implemente todos los recursos relacionados en la misma región que la red virtual (VNet). Para obtener instrucciones, consulte Creación de un nuevo entorno protegido por red con identidad administrada por el usuario.

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 funcionalidad siguen una jerarquía en la que las configuraciones más específicas invalidan las más amplias:

1. valores predeterminados del servicio (búsqueda y almacenamiento administrados por Microsoft): se usa cuando no hay ningún host de capacidades configurado.
2. Anfitrión de capacidad a nivel de cuenta: proporciona valores predeterminados compartidos para todos los proyectos de la cuenta.
3. Project-level capability host: invalida el nivel de cuenta 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, obtendrá un conflicto 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:

• Thread storage: 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.

Configurar anfitriones 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 requeridas (capacidad del host 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 y, opcionalmente, defina los valores predeterminados que los proyectos pueden heredar.

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

Esta configuración invalida los valores predeterminados del servicio y cualquier configuración de nivel de cuenta. Todos los agentes de este proyecto usarán los recursos especificados:

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: Hosts de capacidad del proyecto: crear o actualizar

Opcional: valores predeterminados de nivel de cuenta con invalidaciones de proyecto

Establezca los valores predeterminados compartidos en el nivel de cuenta que se aplican a todos los proyectos:

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:

   • Los hilos de la conversación aparecen en 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

Eliminar un host de capacidad a 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 de 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:

• Consulta anfitriones de capacidad 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 capacidades.
• 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 los valores predeterminados de nivel de cuenta y, a continuación, invalide en el nivel de proyecto según sea necesario.

Pasos siguientes

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