Funktionshosts

Funktionshosts sind Teilressourcen, die Sie sowohl für das Microsoft Foundry-Konto als auch für die Foundry-Projektbereiche konfigurieren. Sie teilen dem Foundry Agent Service mit, wo Agent-Daten gespeichert und verarbeitet werden sollen, einschließlich:

• Kommunikationsverlauf (Threads)
• 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

Capability-Hosts ermöglichen es Ihnen, Ihre eigenen Azure-Ressourcen anstelle der standardmäßigen, von Microsoft verwalteten Plattformressourcen zu 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:

• Threadspeicher (Konversationshistorie, Agentdefinitionen)
• Dateispeicher (hochgeladene Dokumente)
• Vektorsuche (Einbettungen und Abrufen)

Eigene Ressourcen mitbringen

Wenn Sie Kapazitäts-Hosts sowohl auf Konto- als auch auf Projektebene erstellen, speichern und verarbeiten Ihre Azure-Ressourcen Agentdaten. Dies ist die Standardmäßige Agent-Einrichtung. Stellen Sie für die netzwerkgeschützte Standard-Agent-Einrichtung alle zugehörigen Ressourcen in derselben Region wie Ihr virtuelles Netzwerk (VNet) bereit. Anleitungen finden Sie unter Erstellen einer neuen netzwerkgeschützten Umgebung mit vom Benutzer verwalteter Identität.

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

Konfigurationshierarchie

Fähigkeits-Hosts folgen einer Hierarchie, in der spezifischere Konfigurationen umfassendere überschreiben.

1. Service defaults (Microsoft-managed search and storage) – Wird verwendet, wenn kein Funktionshost konfiguriert ist.
2. Host für Funktionen auf Kontoebene: Stellt gemeinsame Standardwerte für alle Projekte unter dem Konto bereit.
3. Projektbezogener Host für Funktionen - Überschreibt die Kontoebene für dieses spezifische Projekt.

Verständnis von Kapazitätsbeschränkungen des Hosts

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 Fähigkeits-Host mit einem anderen Namen im selben Bereich zu erstellen, erhalten Sie einen 409-Konflikt.

• 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 die Ressourcen, die Agentdaten speichern:

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

Fähigkeitshosts konfigurieren

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 zu aktivieren und (optional) Standardwerte zu definieren, die Projekte erben können.

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

Projekt-Applikationshost

Diese Konfiguration setzt die Standardeinstellungen des Diensts und alle Einstellungen auf Kontoebene außer Kraft. Alle Agents in diesem Projekt verwenden Ihre angegebenen 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: Projektfähigkeits-Hosts – erstellen oder aktualisieren

Optional: Standardeinstellungen auf Kontoebene mit Projektüberschreibungen

Legen Sie freigegebene Standardwerte auf Kontoebene fest, die für alle Projekte gelten:

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 Sie Ihre Konfiguration

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

1. Rufen Sie den Kontofunktionshost ab, und bestätigen Sie, dass 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:

   • Konversationsthreads erscheinen in Ihrem Azure Cosmos DB
   • 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 Fähigkeits-Hosts mit der aktualisierten Konfiguration neu.

Löschen von Funktionshosts

Löschen eines Hosts auf Kontoebene

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

Löschen eines Fähigkeits-Hosts auf Projektebene

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

HTTP 409-Konfliktfehler

Problem: Mehrere Kapazitätshosts pro Anwendungsbereich

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 Funktionshost mit einem anderen Namen zu erstellen, wenn bereits ein Funktionshost in demselben Bereich vorhanden ist.

Lösung:

1. Vorhandene Kapazitäts-Hosts prüfen – den Umfang abfragen, um zu sehen, was bereits existiert.
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 Operationen laufen

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
• Überprüfen auf laufende Vorgänge
• Grundlegendes zur aktuellen Konfiguration

2. Implementierung einer 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. Grundlegendes zum idempotenten Verhalten

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 bestehenden Capability Hosts
2. Warten, bis der Löschvorgang abgeschlossen ist
3. Erstellen Sie einen neuen Funktionshost mit der gewünschten Konfiguration

Häufige Szenarien

• Development and testing: Verwenden sie Microsoft verwaltete Ressourcen. Keine Konfiguration des Hosts für Funktionen erforderlich.
• Produktion mit Compliance-Anforderungen: Erstellen Sie Kapazitätshosts mit Ihrer eigenen Azure Cosmos DB, Ihrem Speicher und AI Search.
• Freigegebene Ressourcen über Projekte hinweg: Konfigurieren Sie Standardeinstellungen auf Kontoebene und überschreiben Sie diese dann nach Bedarf auf Projektebene.

Nächste Schritte

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