Compartir por

Hosts de funcionalidad

Nota:

No se admite la actualización de hosts de funcionalidad. Para modificar un host de funcionalidad, debe eliminar el existente y volver a crearlo con la nueva configuración.

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

¿Por qué usar hosts de capacidad?

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

  • Soberanía de 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 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 hosts de capacidad, el servicio de agente usa automáticamente los recursos de Azure que administra Microsoft para:

  • Almacenamiento de hilos (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 funcionalidad tanto a nivel de cuenta como de proyecto, los recursos de Azure almacenan y procesan los datos de los agentes. 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 virtual network (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.

Nota:

Se recomienda usar cuentas y proyectos de Foundry independientes para la configuración del agente estándar y la configuración básica del agente. Evite mezclar tipos de configuración dentro de la misma cuenta de Foundry.

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 de Servicio (búsqueda y almacenamiento administrados por Microsoft): se usa cuando no se configura ningún host de capacidad.
  2. Host de funcionalidad de nivel de cuenta: proporciona valores predeterminados compartidos para todos los proyectos de la cuenta.
  3. Host de capacidad de nivel de proyecto: anula los valores predeterminados de nivel de cuenta y servicio de ese proyecto específico.

Comprender las limitaciones del host de capacidades

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

  • Un anfitrión de capacidad por ámbito: cada cuenta y cada proyecto solo pueden tener un anfitrión de capacidad 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 capacidad aloja los nombres de conexión de referencia que se crean en la cuenta y el proyecto de Foundry. Antes de configurar un host de capacidad de proyecto para la configuración de agentes estándar, cree conexiones para los recursos que guardan los datos del agente:

  • Thread storage: conexión a Azure Cosmos DB
  • File storage: conexión de Azure Storage
  • Vector store: conexión de Azure AI Search

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 Agregar una nueva conexión a su 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 requeridas (anfitrión de capacidad del proyecto)

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

Propiedad Propósito Recurso de Azure requerido Nombre de conexión de ejemplo
threadStorageConnections Almacena definiciones de agente, historial de conversaciones y hilos de chat Azure Cosmos DB "my-cosmosdb-connection"
vectorStoreConnections Gestiona el almacenamiento vectorial para la recuperación y la búsqueda Azure AI Search "my-ai-search-connection"
storageConnections Administra cargas de archivos y almacenamiento de blobs. cuenta de Azure Storage "my-storage-connection"

Propiedad opcional

Propiedad Propósito Recurso de Azure requerido Cuándo usar
aiServicesConnections Utilice sus propias implementaciones de modelos Azure OpenAI Si desea usar modelos de su recurso de Azure OpenAI existente en lugar de los integrados a nivel de cuenta.

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 que especificaste.

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

Nota:

Todos los proyectos de Foundry heredarán esta configuración. A continuación, anule la configuración específica a nivel de proyecto según sea necesario.

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 Azure AI Search

  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

Advertencia

La eliminación de un host de funcionalidad afectará a todos los agentes que dependen de él. Asegúrese de comprender el impacto antes de continuar. Por ejemplo, si elimina el host de funcionalidad de proyecto y cuenta, los agentes del proyecto ya no tendrán acceso a los archivos, subprocesos y almacenes vectoriales a los que tenían acceso anteriormente.

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 funcionalidad de 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."
  }
}

Root cause: Cada cuenta y cada proyecto solo puede tener un host de capacidad 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 a nivel de cuenta y, después, anule en el nivel de proyecto según sea necesario.

Pasos siguientes

  • Last updated on