Hosts de funcionalidad

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

Prerrequisitos

• Un proyecto de Microsoft Foundry
• Si usa sus propios recursos para los datos del agente (configuración estándar del agente), cree los recursos y conexiones de Azure necesarios:
  • Uso de 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 rol propietario para asignar acceso a los recursos de Azure (para la configuración del agente estándar)
  • Para obtener más información, consulte Permisos necesarios y control de acceso basado en rol (RBAC) en Microsoft Foundry.

¿Por qué usar hosts de capacidad?

Los anfitriones de capacidad le permiten usar sus propios recursos de Azure en lugar de utilizar los recursos predeterminados de la plataforma gestionada por Microsoft. Esto le proporciona lo siguiente:

• Soberanía de 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 por Microsoft)

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

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

Traiga sus propios recursos

Al crear anfitriones de capacidad tanto en el nivel de cuenta como de 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 se configura ningún host de funcionalidad.
2. Host de funcionalidad de nivel de cuenta: proporciona valores predeterminados compartidos para todos los proyectos de la cuenta.
3. Host de capacidad a nivel de proyecto: anula los valores predeterminados de nivel de cuenta y servicio para ese proyecto en particular.

Comprender las limitaciones del host de capacidades

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.

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 subprocesos: conexión de Azure Cosmos DB
• Almacenamiento de archivos: conexión de Azure Storage
• Almacén de vectores: conexión de Búsqueda de Azure AI

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

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

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 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 funcionalidad 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: Anfitriones de capacidades 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 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 tiene problemas al crear hosts de funcionalidad, en esta sección se proporcionan soluciones a los problemas y errores más comunes.

Errores de conflicto HTTP 409

Problema: varios hosts de capacidad por ámbito

Síntomas: 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 otro nombre cuando ya existe uno en el mismo ámbito.

Solution:

1. Comprobar los hosts de capacidad existentes: consulte el ámbito para ver qué ya 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.

Solution:

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 de 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 frecuentes

• 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 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