Funktionshosts

Capability Hosts sind Sub-Ressourcen, die Sie sowohl im Bereich des Microsoft Foundry-Kontos als auch im Bereich des Foundry-Projekts konfigurieren. Sie teilen dem Foundry Agent Service mit, wo Agent-Daten gespeichert und verarbeitet werden sollen, einschließlich:

• Konversationsverlauf
• Datei-Uploads
• Vektorspeicher

Voraussetzungen

• Ein Microsoft Foundry-Projekt
• Wenn Sie Ihre eigenen Ressourcen für Agentdaten (Standard-Agent-Setup) verwenden, erstellen Sie die erforderlichen Azure Ressourcen und Verbindungen:
  • Verwenden Ihrer eigenen Ressourcen
  • Hinzufügen einer neuen Verbindung zu Ihrem Projekt
• Erforderliche Berechtigungen:
  • Rolle Mitwirkender im Foundry-Konto zum Erstellen von Funktionshosts
  • Benutzerzugriffsadministrator oder Owner Rolle zum Zuweisen des Zugriffs auf Azure Ressourcen (für die Standard-Agent-Einrichtung)
  • Ausführliche Informationen finden Sie unter Required permissions and Role-based access control (RBAC) in Microsoft Foundry.

Gründe für die Verwendung von Funktionshosts

Mit Fähigkeits-Hosts können Sie Ihre eigenen Azure-Ressourcen anstelle der standardmäßig von Microsoft verwalteten Plattformressourcen verwenden. Dadurch erhalten Sie:

• Datenhoheit – Behalten Sie alle Agentdaten in Ihrem Azure-Abonnement bei.
• Sicherheitskontrolle – Verwenden Sie Ihre eigenen Speicherkonten, Datenbanken und Suchdienste.
• Compliance – Erfüllen Sie bestimmte behördliche oder organisatorische Anforderungen.

Wie funktionieren Funktionshosts?

Das Erstellen von Funktionshosts ist nicht erforderlich. Wenn Agents Ihre eigenen Azure Ressourcen verwenden sollen, erstellen Sie Funktionshosts sowohl im Konto- als auch im Projektbereich.

Standardverhalten (Microsoft verwaltete Ressourcen)

Wenn Sie keine Funktionshosts erstellen, verwendet der Agentdienst automatisch Microsoft verwaltete Azure-Ressourcen für:

• Konversationsspeicher (Konversationsverlauf, Agentdefinitionen)
• Dateispeicher (hochgeladene Dokumente)
• Vektorsuche (Einbettungen und Abrufen)

Bring-deine-eigenen Ressourcen

Wenn Sie Funktionshosts sowohl auf Konto- als auch auf Projektebene erstellen, speichern und verarbeiten Ihre Azure-Ressourcen Agentdaten. Dies ist die Standardmäßige Agent-Einrichtung. Informationen zum Sichern Ihres Agentdiensts finden Sie unter Einrichten privater Netzwerke für den Foundry-Agent-Dienst.

Weitere Informationen zum Standard-Agent-Setup finden Sie unter "Integrierte Unternehmensbereitschaft mit Standard-Agent-Setup".

Konfigurationshierarchie

Fähigkeitshosts arbeiten in zwei unterschiedlichen Geltungsumfängen:

1. Service defaults (Microsoft-managed search and storage) – Wird verwendet, wenn kein Funktionshost konfiguriert ist.
2. Funktion auf Kontoebene hosten – Aktiviert Agent-Dienst auf Kontoebene.
3. Funktionshost auf Projektebene - Definiert, welche BYO-Ressourcen der Agent Service für dieses spezifische Projekt verwendet.

Verstehen von Capability-Host-Einschränkungen

Beachten Sie beim Erstellen von Funktionshosts diese wichtigen Einschränkungen, um Konflikte zu vermeiden:

• Ein Funktionshost pro Bereich: Jedes Konto und jedes Projekt kann nur einen aktiven Funktionshost haben. Wenn Sie versuchen, einen zweiten Funktionshost mit einem anderen Namen im selben Bereich zu erstellen, erhalten Sie einen Fehler von 409.

• Konfigurationen können nicht aktualisiert werden: Wenn Sie die Konfiguration ändern müssen, löschen Sie den vorhandenen Funktionshost, und erstellen Sie ihn neu.

• Voraussetzungen für den Kontofunktionshost: Sie können keinen Projektfunktionshost erstellen, es sei denn, ein Host auf Kontoebene ist bereits vorhanden.

Erstellen von Verbindungen für Funktionshosts

Funktionshosts verweisen auf Verbindungsnamen, die Sie in Ihrem Foundry-Konto und -Projekt erstellen. Bevor Sie einen Projektfunktionshost für die Standard-Agent-Einrichtung konfigurieren, erstellen Sie Verbindungen für Ressourcen, die Agentdaten speichern:

• Konversationsspeicher: Azure Cosmos DB-Verbindung
• File storage: Azure Storage Verbindung
• Vector Store: Azure KI-Suche Verbindung

Wenn Sie Modellbereitstellungen aus Ihrer eigenen Azure OpenAI-Ressource verwenden möchten, erstellen Sie auch eine Azure OpenAI-Verbindung.

Informationen zum Hinzufügen von Verbindungen im Foundry-Portal finden Sie unter Hinzufügen einer neuen Verbindung zu Ihrem Projekt.

Erforderliche Verbindungseigenschaften

Damit der Agent-Dienst Ihre Ressourcen zur Laufzeit korrekt auflösen und verwenden kann, muss jede von einem Fähigkeitshost referenzierte Verbindung über die folgenden ausgefüllten Eigenschaften verfügen:

Das folgende Beispiel zeigt eine ordnungsgemäß konfigurierte Azure Storage Verbindung:

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

Konfigurieren von Funktionshosts

Derzeit verwalten Sie Funktionshosts mithilfe der REST-API. Die SDK-Unterstützung für die Funktionshostverwaltung ist nicht verfügbar.

Erforderliche Eigenschaften (Projektfunktionshost)

Um Ihre eigenen Ressourcen für Agentdaten (Standard-Agent-Setup) zu verwenden, konfigurieren Sie den Projektfunktionshost mit den folgenden Eigenschaften:

Optionale Eigenschaft

Kontofunktionshost

Verwenden Sie einen Kontofunktionshost, um den Agentdienst auf Kontoebene zu aktivieren.

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

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

Referenz: Rest-API für die Verwaltung von Foundry-Konten

Projektfähigkeiten-Host

Der Host für Projektfunktionen ist das, was Agent Service liest, um zu bestimmen, welche BYO-Ressourcen für ein Projekt verwendet werden sollen. Alle Agents in diesem Projekt verwenden die hier referenzierten Ressourcen:

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

Referenz: Projektfunktionshosts – Erstellen oder Aktualisieren

Optional: Verbindungen auf Kontoebene mit Hosts mit Projektfunktion

Sie können auch Verbindungen auf Kontoebene definieren. Wenn unter diesem Konto ein neues Projekt erstellt wird, werden diese Verbindungen vom Projekt geerbt. Die Hostkonfiguration der Projektfunktion wird jedoch nicht geerbt. Sie müssen dennoch einen Projektfunktionshost explizit erstellen und auf die Verbindungen verweisen, die der Agentdienst für dieses Projekt verwenden soll.

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

Überprüfen Ihrer Konfiguration

Führen Sie die folgenden Schritte aus, um zu bestätigen, dass Funktionshosts ordnungsgemäß konfiguriert sind:

1. Rufen Sie den Kontofunktionshost ab, und überprüfen Sie, ob er vorhanden ist.

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

2. Rufen Sie den Projektfunktionshost ab, und bestätigen Sie, dass er auf die erwarteten Verbindungsnamen verweist.

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

3. Testen Sie Ihre Konfiguration, indem Sie einen Test-Agent erstellen und eine Unterhaltung ausführen. Bestätigen Sie folgendes:

   • Unterhaltungen werden in Ihrem Azure Cosmos DB angezeigt.
   • Hochgeladene Dateien werden in Ihrem Azure Storage Konto angezeigt
   • Vektordaten werden in Ihrem Azure KI-Suche Index angezeigt.

4. Wenn Sie Verbindungen aktualisieren oder ändern möchten, wo die Daten gespeichert werden, löschen und erstellen Sie die Kapazitäts-Hosts mit der aktualisierten Konfiguration neu.

Löschen von Kapazitätshosts

Löschen einer Kontoebenen-Funktion-Host

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

Ein Projektfähigkeiten-Host löschen

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

Problembehandlung

Wenn beim Erstellen von Capability-Hosts Probleme auftreten, bietet dieser Abschnitt Lösungen für die häufigsten Fehler.

HTTP 409-Konfliktfehler

Problem: Mehrere Funktionshosts pro Bereich

Symptome: Beim Versuch, einen Funktionshost zu erstellen, erhalten Sie einen 409-Konfliktfehler, obwohl Sie der Meinung sind, dass der Bereich leer ist.

Fehlermeldung:

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

Ursache: Jedes Konto und jedes Projekt kann nur über einen aktiven Funktionshost verfügen. Sie versuchen, einen Kapazitätshost mit einem anderen Namen zu erstellen, obwohl bereits ein Host mit demselben Umfang vorhanden ist.

Lösung:

1. Überprüfung vorhandener Kapazitäts-Hosts – Abfrage des Umfangs, um zu sehen, was bereits vorhanden ist
2. Einheitliche Benennung verwenden – Stellen Sie sicher, dass Sie denselben Namen für alle Anforderungen für denselben Bereich verwenden
3. Überprüfen Sie Ihre Anforderungen – Ermitteln, ob der vorhandene Funktionshost Ihre Anforderungen erfüllt

Überprüfungsschritte: Verwenden Sie die GET-Anforderungen in " Überprüfen Ihrer Konfiguration ", um zu überprüfen, ob bereits ein Funktionshost im Zielbereich vorhanden ist.

Problem: Gleichzeitige Vorgänge werden ausgeführt

Symptome: Sie erhalten einen Konfliktfehler vom Typ 409, der angibt, dass derzeit ein anderer Vorgang ausgeführt wird.

Fehlermeldung:

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

Grundursache: Sie versuchen, einen Funktionshost zu erstellen, während ein anderer Vorgang (Aktualisieren, Löschen, Ändern) im selben Bereich ausgeführt wird.

Lösung:

1. Warten, bis der aktuelle Vorgang abgeschlossen ist – Überprüfen des Status der laufenden Vorgänge
2. Überwachen des Vorgangsfortschritts – Verwenden der Operations-API zum Nachverfolgen des Abschlusses
3. Implementieren von Wiederholungslogik – Verwenden eines exponentiellen Backoffs für temporäre Konflikte

Betriebsüberwachung:

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

Bewährte Methoden zur Konfliktprävention

1. Überprüfung vor der Anforderung

Überprüfen Sie immer den aktuellen Zustand, bevor Sie Änderungen vornehmen:

• Abfragen vorhandener Funktionshosts im Zielbereich
• Prüfen, ob laufende Vorgänge bestehen
• Grundlegendes zur aktuellen Konfiguration

2. Implementieren Sie eine Wiederholungslogik mit exponentiellem Backoff

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. Verständnis des idempotenten Verhaltens

Das System unterstützt idempotente Erstellungsanforderungen:

• Identischer Name + gleiche Konfiguration → Gibt vorhandene Ressource zurück (200 OK)
• Identischer Name + unterschiedliche Konfiguration → Gibt 400 ungültige Anforderung zurück.
• Anderer Name → Gibt 409 Konflikt zurück.

4. Workflow für Konfigurationsänderungen

Da Updates nicht unterstützt werden, folgen Sie dieser Sequenz für Konfigurationsänderungen:

1. Löschen des vorhandenen Funktionshosts
2. Warten, bis der Löschvorgang abgeschlossen ist
3. Erstellen eines neuen Funktionshosts mit der gewünschten Konfiguration

Häufige Szenarien

• Development and testing: Verwenden sie Microsoft verwaltete Ressourcen. Es wird keine Capability-Host-Konfiguration benötigt.
• Produktion mit Complianceanforderungen: Erstellen Sie Kapazitätshosts mit Ihrer eigenen Azure Cosmos DB, Ihrem Speicher und AI Search.
• Freigegebene Ressourcen für alle Projekte: Konfigurieren Sie Verbindungen auf Kontoebene, und erstellen Sie dann für jedes Projekt einen Projektfunktionshost, der explizit auf diese Verbindungen verweist.

Nächste Schritte

• Standard-Agent-Setup
• Einrichten Ihrer Umgebung
• Hinzufügen einer neuen Verbindung zu Ihrem Projekt