Hosts de funcionalidad

Los hosts de funcionalidad son subrecursos que se configuran tanto en los ámbitos de cuenta de Microsoft Foundry como de proyecto 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 contribuidor en la cuenta de Foundry para crear hosts de capacidad
  • User Access Administrator o Owner 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 traer sus propios recursos de Azure en lugar de usar los recursos de plataforma administrados por Microsoft por defecto. 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 funcionalidad. 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 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 hosts de funcionalidad 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. Service - valores predeterminados (búsqueda y almacenamiento administrados por Microsoft): se usa cuando no hay ningún host de capacidades configurado.
2. Host de funcionalidad de nivel de cuenta : proporciona valores predeterminados compartidos para todos los proyectos de la cuenta.
3. Host de capacidades a nivel de proyecto: invalida los valores predeterminados de nivel de cuenta y servicio para ese proyecto específico.

Comprender las restricciones del host de capacidad

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 capacidad con un nombre diferente en el mismo ámbito, se producirá 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:

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

Configuración de hosts de funcionalidad

Actualmente, administra los hosts de funcionalidad mediante la API REST. La compatibilidad del SDK con la gestión del anfitrión 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 capacidades 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 de proyecto - Crear o actualizar

Opcional: valores predeterminados a nivel de cuenta con sobrescrituras 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 funcionalidad 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 funcionalidad 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 capacidad

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 anfitriones de capacidad, esta sección proporciona soluciones a los problemas y errores más comunes.

Errores de conflicto HTTP 409

Problema: múltiples anfitriones 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 un nombre diferente cuando ya existe uno en el mismo ámbito.

Solución:

1. Verificar los hosts de capacidad existentes - Consulte el ámbito para ver lo que 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.

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 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 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: crea hosts de capacidades con Azure Cosmos DB, Storage e AI Search propios.
• 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