Hosty możliwości

Hosty zasobów to zasoby podrzędne konfigurowane w kontekście zarówno konta Microsoft Foundry, jak i projektów Foundry. Informują one usługę agenta Foundry, gdzie mają być przechowywane i przetwarzane dane agenta, w tym:

• Historia konwersacji
• Przekazywanie plików
• Magazyny wektorów

Wymagania wstępne

• Projekt Microsoft Foundry
• Jeśli używasz własnych zasobów na potrzeby danych agenta (konfiguracja agenta standardowego), utwórz wymagane zasoby i połączenia Azure:
  • Korzystanie z własnych zasobów
  • Dodawanie nowego połączenia do projektu
• Wymagane uprawnienia:
  • Rola kontrybutora na koncie usługi Foundry w celu utworzenia hostów dla funkcji
  • Administrator dostępu użytkowników lub Owner aby przypisać dostęp do zasobów Azure (w przypadku standardowej konfiguracji agenta)
  • Aby uzyskać szczegółowe informacje, zobacz Wymagane uprawnienia oraz Kontrola dostępu oparta na rolach (RBAC) w Microsoft Foundry.

Dlaczego warto używać hostów zdolności?

Hosty możliwości pozwalają używać własnych zasobów Azure zamiast domyślnych zasobów platformy zarządzanej przez Microsoft. Zapewnia to:

• Własność danych — zachowaj wszystkie dane agenta w ramach subskrypcji Azure.
• Kontrola zabezpieczeń — użyj własnych kont magazynowych, baz danych i usług wyszukiwania.
• Zgodność — spełnia określone wymagania prawne lub organizacyjne.

Jak działają hosty możliwości?

Tworzenie hostów funkcji nie jest wymagane. Jeśli chcesz, aby agenci używali twoich własnych zasobów Azure, utwórz hosty funkcji zarówno w obrębie konta, jak i projektu.

Zachowanie domyślne (zasoby zarządzane Microsoft)

Jeśli nie utworzysz hostów funkcji, usługa agenta automatycznie używa zasobów Azure zarządzanych przez Microsoft dla:

• Przechowywanie konwersacji (historia konwersacji, definicje agentów)
• Przechowywanie plików (przekazane dokumenty)
• Wyszukiwanie wektorowe (osadzanie i pobieranie)

Przynieś swoje zasoby

Podczas tworzenia hostów funkcji zarówno na poziomie konta, jak i projektu, zasoby Azure przechowują i przetwarzają dane agentów. Jest to standardowa konfiguracja agenta. Aby zabezpieczyć usługę agenta, zobacz Konfigurowanie sieci prywatnej dla usługi Foundry Agent Service.

Aby dowiedzieć się więcej na temat standardowej konfiguracji agenta, zobacz Wbudowana gotowość przedsiębiorstwa ze standardową konfiguracją agenta.

Hierarchia konfiguracji

Hosty funkcji działają w dwóch odrębnych zakresach:

1. Domyślne ustawienia usług (wyszukiwanie i przechowywanie zarządzane przez Microsoft) - używane, gdy nie skonfigurowano hosta możliwości.
2. Host funkcji na poziomie konta — włącza usługę Agent Service na poziomie konta.
3. Host funkcji na poziomie projektu — określa, których zasobów BYO używa usługa Agent Service dla tego konkretnego projektu.

Zrozumienie ograniczeń hosta zdolności

Podczas tworzenia hostów możliwości należy pamiętać o tych ważnych ograniczeniach, aby uniknąć konfliktów:

• Jeden host właściwości na zakres: każde konto i każdy projekt może mieć tylko jeden aktywny host właściwości. Jeśli spróbujesz utworzyć drugi host możliwości o innej nazwie w tym samym zakresie, zostanie wyświetlony błąd 409.

• Nie można zaktualizować konfiguracji: jeśli musisz zmienić konfigurację, usuń istniejący host możliwości i utwórz go ponownie.

• Wymogi wstępne dla funkcjonalności hosta konta: Nie można utworzyć hosta funkcjonalności projektu, chyba że host funkcjonalności na poziomie konta już istnieje.

Tworzenie połączeń dla hostów funkcjonalności

Hosty możliwości odwołują się do nazw połączeń tworzonych na koncie i projekcie usługi Foundry. Przed skonfigurowaniem hosta możliwości projektu dla standardowej konfiguracji agenta utwórz połączenia dla zasobów, które przechowują dane agenta:

• Przechowywanie konwersacji: połączenie z usługą Azure Cosmos DB
• Przechowywanie plików: połączenie z Azure Storage
• Vector store: połączenie Wyszukiwanie AI platformy Azure

Jeśli chcesz użyć wdrożeń modelu z własnego zasobu Azure OpenAI, utwórz również połączenie Azure OpenAI.

Aby dodać połączenia w portalu Foundry, zobacz Dodawanie nowego połączenia do projektu.

Wymagane właściwości połączenia

Aby usługa agenta mogła poprawnie rozpoznać zasoby i korzystać z nich w czasie wykonywania, każde połączenie przywoływalne przez hosta możliwości musi mieć wypełnione następujące właściwości:

W poniższym przykładzie przedstawiono poprawnie skonfigurowane połączenie Azure Storage:

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

Konfigurowanie hostów możliwości

Obecnie można zarządzać hostami funkcjonalności przy użyciu interfejsu API REST. Obsługa zestawu SDK dla zarządzania funkcjami hosta nie jest dostępna.

Wymagane właściwości (funkcjonalności hosta projektu)

Aby użyć własnych zasobów na potrzeby danych agenta (konfiguracja agenta standardowego), skonfiguruj hosta możliwości projektu przy użyciu następujących właściwości:

Właściwość opcjonalna

Gospodarz funkcjonalności konta

Użyj hosta funkcji konta, aby włączyć Agent Service na poziomie konta.

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

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

Dokumentacja: interfejs API REST zarządzania kontami usługi Foundry

Host możliwości projektu

Host funkcji projektu jest używany przez usługę Agent Service do określenia, które zasoby BYO mają być używane w danym projekcie. Wszyscy agenci w tym projekcie będą używać zasobów, do których odwołuje się tutaj:

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

Odnośnik: Hosty funkcji projektu — tworzenie lub aktualizacja

Opcjonalnie: połączenia na poziomie konta z hostami obsługującymi możliwości projektu

Możesz również zdefiniować połączenia na poziomie konta. Po utworzeniu nowego projektu na tym koncie te połączenia są dziedziczone przez projekt. Jednak konfiguracja hosta możliwości dla projektu nie jest dziedziczona — nadal należy jawnie utworzyć host możliwości dla projektu i wskazać połączenia, z których ma korzystać Agent Service w tym projekcie.

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

Weryfikowanie konfiguracji

Wykonaj następujące kroki, aby potwierdzić, że hosty funkcji są poprawnie skonfigurowane:

1. Pobierz host możliwości konta i upewnij się, że on istnieje.

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

2. Pobierz hosta możliwości projektu i potwierdź, że odwołuje się do oczekiwanych nazw połączeń.

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

3. Przetestuj konfigurację, tworząc agenta testowego i uruchamiając konwersację. Potwierdź, że:

   • Konwersacje są wyświetlane w Azure Cosmos DB.
   • Przekazane pliki są wyświetlane na koncie Azure Storage
   • Dane wektorowe są wyświetlane w indeksie Wyszukiwanie AI platformy Azure

4. Jeśli zaktualizujesz połączenia lub chcesz zmienić miejsce przechowywania danych, usuń i ponownie utwórz hosty funkcjonalności za pomocą zaktualizowanej konfiguracji.

Usuwanie hostów możliwości

Usuwanie hosta funkcjonalności na poziomie konta

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

Usuwanie hosta możliwości na poziomie projektu

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

Rozwiązywanie problemów

Jeśli występują problemy podczas tworzenia hostów możliwości, ta sekcja zawiera rozwiązania najczęstszych problemów i błędów.

Błędy HTTP 409 Konflikt

Problem: Wiele hostów funkcji w ramach zakresu

Objawy: Podczas próby utworzenia hosta funkcji występuje błąd 409 Konflikt, chociaż sądzisz, że zakres jest pusty.

Komunikat o błędzie:

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

Przyczyna: Każde konto i każdy projekt mogą mieć tylko jednego aktywnego hosta możliwości. Próbujesz utworzyć hosta funkcji o innej nazwie, chociaż już istnieje taki sam w tym samym zakresie.

Rozwiązanie:

1. Sprawdź istniejące hosty funkcji — wykonaj zapytanie o zakres, aby zobaczyć, co już istnieje
2. Użyj spójnego nazewnictwa — upewnij się, że używasz tej samej nazwy we wszystkich żądaniach dla tego samego zakresu
3. Przejrzyj wymagania — oceń, czy istniejący host funkcjonalności spełnia Twoje potrzeby

Kroki weryfikacji: Użyj żądań GET w sekcji Weryfikowanie konfiguracji, aby potwierdzić, czy serwer funkcji już istnieje w docelowym zakresie.

Problem: Współbieżne operacje w toku

Objawy: Zostanie wyświetlony błąd 409 Konflikt wskazujący, że inna operacja jest obecnie uruchomiona.

Komunikat o błędzie:

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

Przyczyna: Próbujesz utworzyć hosta funkcjonalności, podczas gdy inna operacja (aktualizacja, usuwanie, modyfikowanie) jest w toku w tym samym zakresie.

Rozwiązanie:

1. Poczekaj na zakończenie bieżącej operacji — sprawdź stan bieżących operacji
2. Monitorowanie postępu operacji — śledzenie ukończenia za pomocą interfejsu API operacji
3. Implementowanie logiki ponawiania prób — używanie wycofywania wykładniczego w przypadku konfliktów tymczasowych

Monitorowanie operacji:

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

Najlepsze rozwiązania dotyczące zapobiegania konfliktom

1. Sprawdzanie poprawności przed żądaniem

Przed wprowadzeniem zmian zawsze sprawdź bieżący stan:

• Przeprowadzanie zapytań o istniejące hosty funkcji w docelowym zakresie
• Sprawdź bieżące operacje
• Omówienie bieżącej konfiguracji

2. Zaimplementuj logikę ponawiania przy użyciu wycofywania wykładniczego

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. Omówienie zachowania idempotentnego

System obsługuje idempotentne żądania tworzenia:

• Ta sama nazwa i ta sama konfiguracja → Zwraca istniejący zasób (200 OK)
• Ta sama nazwa i inna konfiguracja → Zwraca 400 nieprawidłowych żądań
• Inna nazwa → Zwraca Konflikt 409

4. Przepływ pracy zmiany konfiguracji

Ponieważ aktualizacje nie są obsługiwane, postępuj zgodnie z tą sekwencją zmian konfiguracji:

1. Usuwanie istniejącego hosta możliwości
2. Poczekaj na zakończenie usuwania
3. Tworzenie nowego hosta możliwości z żądaną konfiguracją

Typowe scenariusze

• Development i testowanie: używaj zasobów zarządzanych przez Microsoft. Nie jest wymagana żadna konfiguracja hosta możliwości.
• Production z wymaganiami dotyczącymi zgodności: Tworzenie hostów zdolności przy użyciu własnych Azure Cosmos DB, Storage i wyszukiwania sztucznej inteligencji.
• Zasoby współdzielone między projektami: skonfiguruj połączenia na poziomie konta, a następnie utwórz host funkcji projektu dla każdego projektu, jawnie odwołujący się do tych połączeń.

Następne kroki

• Konfiguracja agenta standardowego
• Konfigurowanie środowiska
• Dodawanie nowego połączenia do projektu