Einrichten von Standard-Agent-Ressourcen

Das Standard-Agent-Setup verwendet vom Kunden verwaltete Azure-Ressourcen, um den Agentstatus zu speichern und alle Agentdaten unter Ihrer Kontrolle zu behalten. Verwenden Sie das Standardsetup, wenn Sie vollständige Datenhoheit, Compliance mit Unternehmenssicherheitsrichtlinien oder Isolation auf Projektebene benötigen.

In diesem Setup:

  • Agentzustände (Unterhaltungen, Antworten) werden in Ihren eigenen Azure-Ressourcen gespeichert.
  • Sie behalten die vollständige Kontrolle über die Datenresidenz und den Zugriff.

Tipp

Eine einfachere Einrichtung, die von Microsoft verwaltete Ressourcen verwendet, finden Sie unter "Umgebungssetup ", und wählen Sie die Grundlegende Agent-Setupoption aus.

Voraussetzungen

Ressourcenübersicht

Wichtig

Standardsetups erfordern, dass Sie BYO-Ressourcen (Bring Your Own) verwenden, damit alle Agentdaten in Ihrem Azure-Mandanten verbleiben:

Ressource Was es speichert
Azure Storage (BYO-Dateispeicher) Von Entwicklern und Endbenutzern hochgeladene Dateien
Azure AI Search (BYO Search) Vom Agent erstellte Vektorspeicher
Azure Cosmos DB (BYO Thread Storage) Nachrichten, Aufgezeichnete Unterhaltungen und Agentmetadaten

Alle vom Foundry Agent Service verarbeiteten Daten werden automatisch in diesen Ressourcen gespeichert und helfen Ihnen dabei, Complianceanforderungen und Unternehmenssicherheitsstandards zu erfüllen.

Cosmos DB Durchsatzanforderungen

Ihr Azure Cosmos DB für NoSQL-Konto muss über eine Gesamtdurchsatzgrenze von mindestens 3000 RU/s verfügen. Sowohl der bereitgestellte Durchsatz als auch der Serverless-Modus werden unterstützt.

Standardeinrichtung stellt drei Container in Ihrem Cosmos DB-Konto bereit, die jeweils 1000 RU/s benötigen:

Container Zweck
thread-message-store Endbenutzerkommunikationen
system-thread-message-store Interne Systemmeldungen
agent-entity-store Agentmetadaten (Anweisungen, Tools, Name)

Bei mehreren Projekten unter dem selben Foundry-Konto multiplizieren Sie die Werte mit der Anzahl der Projekte. Beispielsweise benötigen zwei Projekte mindestens 6000 RU/s (3 Container × 1000 RU/s × 2 Projekte).

Datenisolation auf Projektebene

Standardsetup erzwingt standardmäßig die Datenisolation auf Projektebene. In Ihrem Speicherkonto werden automatisch zwei Blobspeichercontainer bereitgestellt: eine für Dateien und eine für Zwischensystemdaten (Blöcke, Einbettungen). Drei Container werden in Ihrem Cosmos DB-Konto bereitgestellt: eines für Benutzerthreads, eine für Systemnachrichten und eine für Agentkonfigurationsdaten wie Anweisungen, Tools und Namen. Dieses Standardverhalten reduziert die Einrichtungskomplexität und erzwingt gleichzeitig strenge Datengrenzen zwischen Projekten.

Kapazitäts-Hosts

Capability Hosts sind Unterressourcen sowohl beim Konto als auch beim Projekt und ermöglichen die Interaktion mit dem Agenten-Service.

  • Account-Fähigkeits-Host: Hat einen leeren Anforderungskörper, außer für den Parameter capabilityHostKind="Agents".
  • Host für Projektfähigkeit: Gibt Ressourcen zum Speichern des Agentstatus an, entweder durch Microsoft verwaltete Mehrmandantenfähigkeit (grundlegende Einrichtung) oder von Kunden bereitgestellte Ressourcen mit einem einzelnen Mandanten (Standardsetup). Der Host der Projektfunktion fungiert als Projekteinstellungen.

Einschränkungen

  • Sie können den Funktionshost nicht aktualisieren, nachdem er für ein Projekt oder Konto festgelegt wurde.

Bereitstellen von Ressourcen schritt für Schritt

Hinweis

Das Foundry-Portal unterstützt derzeit nur die grundlegende Agent-Einrichtung. Verwenden Sie zum Konfigurieren der Standard-Agenten-Einrichtung die manuellen Schritte oder die in diesem Abschnitt beschriebene Bicep-Vorlage.

Manuelle Bereitstellung

Führen Sie die folgenden Schritte aus, um alle Ressourcen, die für die Standardmäßige Agent-Einrichtung erforderlich sind, manuell bereitzustellen. Planen Sie ungefähr 30-45 Minuten für den kompletten Bereitstellungsprozess ein.

Phase 1: Erstellen abhängiger Ressourcen

  1. Erstellen oder wiederverwenden Sie die folgenden Ressourcen. Sie können neue Ressourcen erstellen oder die Ressourcen-ID vorhandener Ressourcen übergeben:
    • Azure Cosmos DB für NoSQL-Konto
    • Azure Storage-Konto
    • Azure AI Search-Ressource
    • Azure Key Vault-Ressource (wird zum Verwalten von geheimen Schlüsseln und Verbindungszeichenfolgen für die Agentinfrastruktur verwendet)
    • [Optional] Azure Application Insights-Ressource
    • [Optional] Vorhandene Gießereiressource

Phase 2: Erstellen von Gießereiressourcen und -verbindungen

  1. Erstellen Sie eine Microsoft Foundry-Ressource.
  2. Erstellen von Verbindungen auf Kontoebene:
    • Erstellen Sie eine Kontoverbindung mit der Application Insights-Ressource.
  3. Stellen Sie gpt-4o oder ein anderes agentkompatibles Modell bereit.
  4. Erstellen Sie ein Projekt.
  5. Erstellen von Projektverbindungen:
    • [Falls angegeben] Projektverbindung zur Foundry-Ressource.
    • Verbindung des Projekts mit dem Azure Storage-Konto.
    • Verbindung des Projekts mit der Azure AI Suchressource.
    • Projektverbindung mit dem Cosmos DB-Konto.

Phase 3: Zuweisen von Rollen zur verwalteten Identität des Projekts

Die im Rahmen des Projekts verwaltete Identität umfasst sowohl die vom System zugewiesene verwaltete Identität (System-assigned Managed Identity, SMI) als auch die vom Benutzer zugewiesene verwaltete Identität (User-assigned Managed Identity, UMI).

  1. Weisen Sie die projektverwaltete Identität (für SMI) den folgenden Rollen zu:
    • Cosmos DB Operator für die Ressource Cosmos DB auf Kontoebene.
    • Speicherkontomitwirkender auf Kontoebene für die Speicherkontoressource.

Phase 4: Konfigurieren von Funktionshosts

  1. Setzen Sie den Host für Kontofunktionen mit einem leeren Eigenschaftenabschnitt fest.
  2. Legen Sie den Projektfunktionshost mit Cosmos DB-, Azure Storage- und AI-Suchverbindungen fest.

Phase 5: Zuweisen präziser Ressourcenberechtigungen

  1. Weisen Sie die vom Projekt verwaltete Identität (SMI und UMI) den folgenden Rollen für die angegebenen Ressourcenbereiche zu:
    • Azure AI Search (Zuweisung entweder vor oder nach der Erstellung des Fähigkeits-Hosts):
      • Suchindexdatenmitwirkender
      • Suchdienstmitwirkender
    • Azure Blob Storage-Container: <workspaceId>-azureml-blobstore
      • Beitragender zu Speicher-Blob-Daten
    • Azure Blob Storage-Container: <workspaceId>-agents-blobstore
      • Besitzer von Speicher-BLOB-Daten
    • Cosmos DB für NoSQL-Datenbank: enterprise_memory
      • Cosmos DB Integrierter Datenmitwirkender
      • Bereich: Datenbankebene, um alle Container abzudecken (es ist keine einzelne containerspezifische Rollenzuweisung erforderlich).

Phase 6: Gewähren des Entwicklerzugriffs

  1. Weisen Sie allen Entwicklern, die Agents im Projekt erstellen oder bearbeiten müssen, die Azure AI-Benutzerrolle im Projektbereich zu.

Verwenden einer Bicep-Vorlage

Verwenden Sie ein vorhandenes Azure OpenAI-, Azure Storage-Konto, Azure Cosmos DB für NoSQL-Konto oder Azure AI Search-Ressource, indem Sie die vollständige Azure Resource Manager (ARM)-Ressourcen-ID in der Standard-Agent-Vorlagendatei bereitstellen.

Verwenden einer vorhandenen Azure OpenAI-Ressource

  1. Führen Sie die Schritte im Umgebungssetup aus, um die Ressourcen-ID des Findry Tools-Kontos abzurufen.

  2. Ersetzen Sie in der Standard-Agent-Vorlagendatei den folgenden Platzhalter:

    existingAoaiResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{serviceName}

Verwenden eines vorhandenen Azure Storage-Kontos für die Dateispeicherung

  1. Melden Sie sich bei der Azure CLI an, und wählen Sie das Abonnement mit Ihrem Speicherkonto aus:

    az login

  2. Führen Sie den folgenden Befehl aus, um die Ressourcen-ID Ihres Speicherkontos abzurufen:

    az storage account show --resource-group <your-resource-group> --name <your-storage-account> --query "id" --output tsv

    Die Ausgabe ist der aiStorageAccountResourceID Wert, den Sie in der Vorlage benötigen.

  3. Ersetzen Sie in der Standard-Agent-Vorlagendatei den folgenden Platzhalter:

    aiStorageAccountResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}

Verwenden Sie ein bestehendes Azure Cosmos DB NoSQL-Konto zur Threadspeicherung.

Für jedes Foundry-Konto wird ein Azure Cosmos DB für NoSQL-Konto erstellt. Informationen zu Durchsatzanforderungen und Multiprojektskalierung finden Sie unter Cosmos DB-Durchsatzanforderungen.

Hinweis

Unzureichende RU/s-Kapazität im Cosmos DB-Konto führt zu Fehlern bei der Bereitstellung von Funktionshosts während der Bereitstellung.

  1. Melden Sie sich bei der Azure CLI an, und wählen Sie das Abonnement mit Ihrem Cosmos DB-Konto aus:

    az login

  2. Führen Sie den folgenden Befehl aus, um Ihre Azure Cosmos DB-Kontoressourcen-ID abzurufen:

    az cosmosdb show --resource-group <your-resource-group> --name <your-cosmosdb-account> --query "id" --output tsv

    Die Ausgabe ist der cosmosDBResourceId Wert, den Sie in der Vorlage benötigen.

  3. Ersetzen Sie in der Standard-Agent-Vorlagendatei den folgenden Platzhalter:

    cosmosDBResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{cosmosDbAccountName}

Verwenden einer vorhandenen Azure AI Search-Ressource

  1. Melden Sie sich bei der Azure CLI an, und wählen Sie das Abonnement mit Ihrer Suchressource aus:

    az login

  2. Führen Sie den folgenden Befehl aus, um Ihre Azure AI Search-Ressourcen-ID abzurufen:

    az search service show --resource-group <your-resource-group> --name <your-search-service> --query "id" --output tsv

  3. Ersetzen Sie in der Standard-Agent-Vorlagendatei den folgenden Platzhalter:

    aiSearchServiceResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}

Überprüfen Des Setups

Überprüfen Sie nach Abschluss der Bereitstellung, ob das Setup ordnungsgemäß funktioniert:

  1. Navigieren Sie im Azure-Portal zu Ihrem Foundry-Projekt, und vergewissern Sie sich, dass alle Verbindungen (Storage, Cosmos DB, AI Search) unter den Projekteinstellungen angezeigt werden.
  2. Überprüfen Sie, ob der Status des Funktionshosts sowohl für das Konto als auch für das Projekt als erfolgreich angezeigt wird.
  3. Überprüfen Sie Rollenzuweisungen, indem Sie zur Access Control (IAM) -Seite der einzelnen Ressourcen navigieren und bestätigen, dass die vom Projekt verwaltete Identität die erwarteten Rollen aufweist.
  4. Erstellen Sie einen Test-Agent, um die End-to-End-Funktionalität zu bestätigen.

Behandeln häufiger Probleme

Symptom Ursache Auflösung
CapabilityHostProvisioningFailed oder der Funktionshoststatus zeigt "Fehlgeschlagen" an. Unzureichender Durchsatz für Cosmos DB Stellen Sie sicher, dass Ihr Cosmos DB-Konto mindestens 3000 RU/s hat (1000 RU/s pro Container × 3 Container). Multiplizieren Sie bei mehreren Projekten mit der Anzahl der Projekte.
403 Forbidden wenn der Agent Dateien liest oder schreibt Fehlende Speicherrollenzuweisungen Überprüfen Sie, ob die vom Projekt verwaltete Identität über Mitwirkender für Speicher-BLOB-Daten für den <workspaceId>-azureml-blobstore Container und Besitzer von Speicher-BLOB-Daten für den <workspaceId>-agents-blobstore Container verfügt.
SearchIndexNotFound oder 403 bei Suchvorgängen Fehlende Suchrollen Vergewissern Sie sich, dass die verwaltete Identität des Projekts sowohl den Suchindexdatenmitwirkenden als auch den Suchdienstmitwirkenden in Ihrer Azure AI Search-Ressource aufweist.
AuthorizationFailed beim Erstellen oder Bearbeiten von Agenten Fehlende Benutzerrolle Weisen Sie dem Entwickler die Azure AI-Benutzerrolle im Projektbereich zu.
Aktualisierungsanforderung an den Fähigkeits-Host gibt 400 BadRequest zurück Aktualisierung nicht unterstützt Funktionshosts können nach der Erstellung nicht aktualisiert werden. Löschen Sie das Projekt, und erstellen Sie es neu, wenn Konfigurationsänderungen erforderlich sind.

Verwandte Inhalte

  • Last updated on