HeyRocky

Connect Hermes to Microsoft Foundry

Hermes uses the azure-foundry provider for Microsoft Foundry and Azure OpenAI resources. A resource may expose an OpenAI-style endpoint for GPT, Llama, Mistral, or other deployments, or an Anthropic Messages-style endpoint for Claude. The setup flow probes the endpoint and attempts to select the matching transport.

This article is provider-specific. It complements general model-routing guidance by focusing on Azure endpoint shape, authentication, RBAC, and deployment verification.

Choose the endpoint and authentication path

Have the exact inference endpoint and deployment name available. Then choose one authentication mode:

  • Microsoft Entra ID: the recommended keyless production path in the official guide. The runtime identity needs the Azure AI User role, which may appear as Foundry User during Microsoft’s rename rollout.
  • API key: use the key from the resource’s Keys and Endpoint page and keep it in the Hermes secret environment, not in article text, prompts, or source control.

Entra ID uses DefaultAzureCredential, so the winning credential may be a managed identity, workload identity, Azure CLI login, service principal, or another supported Azure identity source. Do not assume a successful local az login proves the production identity has access.

Setup checklist

  • Create or identify a Foundry or Azure OpenAI resource with at least one deployed model.
  • Copy the exact inference endpoint, not a portal or project-management URL.
  • Decide whether the endpoint is OpenAI-style or Anthropic-style; let Hermes probe it first.
  • For Entra ID, assign Azure AI User or the currently displayed equivalent to the runtime principal.
  • For API-key mode, place the key in the supported secret store or environment path.
  • Run hermes model, select Azure Foundry, enter the endpoint, and choose the authentication mode.
  • Select a detected deployment or enter the deployment name manually when probing is blocked.
  • Run hermes doctor from the environment that will actually host Hermes.
  • Test one response and one harmless tool call before enabling production traffic.
hermes model
hermes doctor

Transport and private endpoints

OpenAI-style endpoints normally use chat_completions or a runtime-selected Responses path; Anthropic-style endpoints use anthropic_messages. Model families and Azure API behavior evolve, so prefer the current wizard and runtime routing over hard-coding assumptions from a copied example.

A private, firewalled, or IP-restricted endpoint may reject model probes even when runtime inference will work. In that case, manual deployment entry is an expected fallback—not proof that the endpoint is broken. Save the configuration, validate from the target network, and set the API mode explicitly only when the probe remains wrong.

For Entra ID, role propagation can take several minutes. Managed identities also need the role on the Foundry resource itself; assigning access only to a parent project or a developer account may not authorize the runtime.

Common pitfalls

  • Entering a management URL instead of the model inference endpoint.
  • Assuming every Foundry model uses the same wire format.
  • Confusing the model catalog returned by an endpoint with the resource’s deployed model names.
  • Adding /v1 or api-version fragments by hand and producing a doubled or malformed Anthropic URL.
  • Giving a user account RBAC while the workload actually runs as a managed identity.
  • Repeatedly retrying authentication before allowing a new role assignment to propagate.
  • Storing a static key in config.yaml when Entra ID or the secret environment is intended.

Verification steps

  1. Run hermes doctor and confirm the selected authentication chain can acquire credentials from the target environment.
  2. Inspect the saved provider, base URL, API mode, deployment name, and context length without printing secret values.
  3. Start a fresh session and send a small prompt to the selected deployment.
  4. Exercise a harmless tool call to verify the detected transport supports the normal Hermes agent loop.
  5. For a gateway or hosted agent, repeat the smoke test under its managed identity rather than relying on a developer workstation result.

Official documentation

https://hermes-agent.nousresearch.com/docs/guides/azure-foundry

Related pages