Zwei API-Formate unter einem Foundry-Dach

Microsoft Foundry kann Modelle über unterschiedliche Protokolle ausliefern. GPT-, Llama- oder Mistral-Deployments verwenden typischerweise einen OpenAI-artigen Endpoint. Claude-Deployments können über eine Anthropic-Messages-Route laufen. Hermes erkennt Pfad und Antwortform während des Wizards und wählt den passenden Transport.

RouteTypische ModelleHermes API-Modus
...openai.azure.com/openai/v1GPT, Llama, Mistral, Open-Weightchat_completions beziehungsweise automatisch Responses für passende Familien
...services.ai.azure.com/anthropicClaude in Microsoft Foundryanthropic_messages

API-Key oder Entra ID?

Entra ID nutzt Azure Identity und die Standard-Credential-Chain. Lokal kann ein az login greifen; auf Azure-Compute eine Managed Identity; in AKS Workload Identity; in CI ein Service Principal oder besser föderierte Identität. Der Agent muss keine langlebigen Modell-Keys speichern.

  • Rolle auf der konkreten Foundry-Ressource vergeben, nicht nur auf einem thematisch ähnlichen Projekt.
  • Bei User Assigned Managed Identity die korrekte AZURE_CLIENT_ID setzen.
  • Rollenpropagation kann mehrere Minuten dauern; 401 direkt nach Zuweisung ist nicht ungewöhnlich.
  • Für lokale Entwicklung az login erneuern und hermes doctor ausführen.
AuthVorteilGeeignet fürRisiko
API-KeySchnell und universellPilot, private Endpoint-Situationen, einfache TestsGemeinsames langlebiges Secret, Rotation und Attribution
Entra IDKurzlebige Tokens, RBAC, IdentitätsauditVM, AKS, App Service, Functions, CI und lokale EntwicklungRollen- und Credential-Chain müssen korrekt sein

Setup-Wizard und Beispielkonfiguration

  1. 01

    Deployment in Foundry prüfen

    Endpoint, Deployment-ID, Region, Modellzugang und gewünschten API-Typ dokumentieren.

  2. 02

    Identität berechtigen

    Für Entra ID die passende Azure-AI-/Foundry-User-Rolle auf der Ressource vergeben.

  3. 03

    Hermes-Wizard starten

    Über hermes model Azure Foundry auswählen, Endpoint und Authentifizierung angeben.

  4. 04

    Probe auswerten

    Der Wizard versucht Modelle und Transport zu erkennen. Bei privater Firewall kann man bewusst manuell fortfahren.

  5. 05

    Diagnose und Test

    Mit hermes doctor Credential-Chain prüfen und danach eine kleine Tool-Aufgabe ausführen.

Wizard
az login
hermes model
# Azure Foundry → Endpoint → Entra ID
hermes doctor
Beispiel Entra-ID-Konfiguration
model:
  provider: azure-foundry
  base_url: https://my-resource.openai.azure.com/openai/v1
  api_mode: chat_completions
  auth_mode: entra_id
  default: my-gpt-deployment
  context_length: 128000

Deployment-Muster für Unternehmen

Lokal

Azure CLI Credential

Entwickler meldet sich mit az login an; Hermes nutzt die vorhandene Identität. Gut für Tests, nicht für unbeaufsichtigte Produktion.

Azure VM

Managed Identity

System- oder benutzerzugewiesene Identität erhält RBAC auf Foundry. Keine Modell-Keys auf der VM.

AKS

Workload Identity

Service Account mit föderierter Identität statt veralteter Pod-Identity-Muster.

CI/CD

Föderation oder Service Principal

Kurzlebige OIDC-Tokens bevorzugen; Secrets nur wenn der Runner keine Föderation unterstützt.

Hosted Agent

Agent Identity

Die Identität des gehosteten Agenten selbst benötigt den Ressourcenzugriff, nicht nur der menschliche Projektbesitzer.

Sovereign Cloud

Authority Host

Für Government- oder China-Cloud den passenden AZURE_AUTHORITY_HOST konfigurieren.

Fehlerbilder: API-Modus, URL, Scope und RBAC

FehlerWahrscheinlicher GrundPrüfung
Credential chain exhaustedKeine nutzbare Azure Identityaz login, Managed Identity oder AZURE_* Variablen prüfen
401 nach Entra-WechselRolle fehlt, noch nicht propagiert oder falscher ScopeRollenbindung an Ressource und Standard-Scope prüfen
404 mit doppeltem /v1/messagesVeraltete/manuelle Anthropic-Base-URLHermes aktualisieren und /v1 nicht doppelt eintragen
Wizard findet keine ModellePrivate Firewall oder Endpoint erlaubt keine DiscoveryAPI-Modus und Deployment-ID manuell setzen
GPT-5/Responses-FehlerFalscher Transport oder veraltete VersionAktuelles Hermes nutzen; Familienrouting und Endpoint prüfen

Häufige Fragen

Unterstützt Hermes Claude über Microsoft Foundry?

Ja. Anthropic-artige Foundry-Routen können über anthropic_messages genutzt werden; Endpoint und Authentifizierung werden vom Wizard erkannt oder manuell gesetzt.

Ist Entra ID besser als ein API-Key?

Für produktive Azure-Umgebungen meist ja: kurzlebige Tokens, RBAC und bessere Attribution. Ein API-Key kann für einen schnellen Pilot einfacher sein.

Welche Azure-Rolle braucht Hermes?

Die offizielle Hermes-Anleitung nennt Azure AI User beziehungsweise je nach Tenant den umbenannten Foundry-User-Rollennamen auf der Foundry-Ressource.

Warum erkennt der Wizard keine Deployments?

Private oder gefilterte Endpoints blockieren Discovery-Aufrufe. Du kannst API-Modus und Deployment-ID trotzdem manuell speichern und später im Zielnetz testen.

Quellen, Methodik und Aktualität

Dieser Beitrag wurde aus praktischer Arbeit mit Hermes Agent und den unten verlinkten Primärquellen erstellt. Produktstände ändern sich schnell; Versions- und Befehlsangaben wurden zuletzt am geprüft.

  1. Microsoft Foundry Guide – Nous Research
  2. Microsoft Entra ID for Azure AI – Microsoft
  3. DefaultAzureCredential – Microsoft
  4. Hermes Environment Variables – Nous Research