Hermes Agent 接入 Azure AI Foundry：微软 Azure AI 服务集成

Hermes Agent 原生支持 Azure AI Foundry（以及 Azure OpenAI）作为一级提供商。单个 Azure 资源可以托管两种不同传输格式的模型：OpenAI 风格的 chat/completions 端点用于 GPT、Llama、Mistral 等模型，Anthropic 风格的 messages 端点用于 Claude 模型。设置向导会自动探测端点，检测传输协议、可用部署以及每个模型的上下文长度。

前提条件

• 一个 Azure AI Foundry 或 Azure OpenAI 资源，且至少包含一个模型部署
• 该资源的 API 密钥（可在 Azure Portal 的 "Keys and Endpoint" 中获取）
• 部署的端点 URL

快速开始

hermes model
# → Select "Azure Foundry"
# → Enter your endpoint URL
# → Enter your API key
# Hermes probes the endpoint and auto-detects transport + models
# → Pick a model from the list (or type a deployment name manually)

向导会执行以下步骤：

1. 嗅探 URL 路径 — 以 /anthropic 结尾的 URL 会被识别为 Azure Foundry Claude 路由。
2. 探测 GET <base>/models — 如果端点返回 OpenAI 格式的模型列表，Hermes 会切换到 chat_completions 模式，并用返回的部署 ID 预填充选择器。
3. 探测 Anthropic Messages 格式 — 对于不暴露 /models 但接受 Anthropic Messages 格式的端点的回退方案。
4. 回退到手动输入 — 拒绝所有探测的私有/受限端点仍然可用；你可以手动选择 API 模式并输入部署名称。

所选模型的上下文长度通过 Hermes 标准元数据链（models.dev、提供商元数据以及硬编码的模型族回退）解析，并存储在 config.yaml 中，以便模型正确设置自身的上下文窗口。

配置（写入 config.yaml）

运行向导后，你会看到类似如下配置：

model:
  provider: azure-foundry
  base_url: https://my-resource.openai.azure.com/openai/v1
  api_mode: chat_completions         # or "anthropic_messages"
  default: gpt-5.4-mini              # your deployment / model name
  context_length: 400000             # auto-detected

在 ~/.hermes/.env 中：

OpenAI 风格端点（GPT、Llama 等）

Azure OpenAI 的 v1 GA 端点只需极少量修改即可使用标准 openai Python 客户端：

model:
  provider: azure-foundry
  base_url: https://my-resource.openai.azure.com/openai/v1
  api_mode: chat_completions
  default: gpt-5.4

重要行为：

• GPT-5.x、codex 和 o 系列会自动路由到 Responses API。 Azure Foundry 将 GPT-5 / codex / o1 / o3 / o4 模型部署为仅支持 Responses API — 对它们调用 /chat/completions 会返回 400 "The requested operation is unsupported."。Hermes 根据模型名称检测这些模型族，并将 api_mode 透明升级为 codex_responses，即使 config.yaml 中仍然显示 api_mode: chat_completions。GPT-4、GPT-4o、Llama、Mistral 等其他部署继续使用 /chat/completions。
• 自动使用 max_completion_tokens。 Azure OpenAI（与直接使用 OpenAI 一样）要求 gpt-4o、o 系列和 gpt-5.x 模型使用 max_completion_tokens。Hermes 会根据端点自动发送正确的参数。
• 需要 api-version 的 v1 之前的端点。 如果你使用的是旧版 base URL，如 https://<resource>.openai.azure.com/openai?api-version=2025-04-01-preview，Hermes 会提取查询字符串并通过 default_query 在每次请求中转发（OpenAI SDK 在拼接路径时会丢弃该参数）。

Anthropic 风格端点（通过 Azure Foundry 使用 Claude）

对于 Claude 部署，使用 Anthropic 风格的路由：

model:
  provider: azure-foundry
  base_url: https://my-resource.services.ai.azure.com/anthropic
  api_mode: anthropic_messages
  default: claude-sonnet-4-6

重要行为：

• 从 base URL 中移除 /v1。 Anthropic SDK 会在每个请求 URL 后追加 /v1/messages — Hermes 在将 URL 传递给 SDK 之前移除尾部的 /v1，以避免双重 /v1 路径。
• api-version 通过 default_query 发送，而非追加到 URL。 Azure Anthropic 要求 api-version 查询字符串。将其写入 base URL 会产生 /anthropic?api-version=.../v1/messages 这样的畸形路径并返回 404。Hermes 改为通过 Anthropic SDK 的 default_query 传递 api-version=2025-04-15。
• 禁用 OAuth token 刷新。 Azure 部署使用静态 API 密钥。适用于 Anthropic Console 的 ~/.claude/.credentials.json OAuth token 刷新循环在 Azure 端点上会被明确跳过，以防止 Claude Code OAuth token 在会话中覆盖你的 Azure 密钥。

替代方案：provider: anthropic + Azure base URL

如果你已经配置了 provider: anthropic，只想将端点指向 Azure AI Foundry 来使用 Claude，可以完全跳过 azure-foundry provider：

model:
  provider: anthropic
  base_url: https://my-resource.services.ai.azure.com/anthropic
  key_env: AZURE_ANTHROPIC_KEY
  default: claude-sonnet-4-6

在 ~/.hermes/.env 中设置 AZURE_ANTHROPIC_KEY。Hermes 检测到 base URL 中的 azure.com，会绕过 Claude Code OAuth token 链，使 Azure 密钥直接通过 x-api-key 认证使用。

key_env 是规范的 snake_case 字段名；api_key_env（以及 camelCase 的 keyEnv / apiKeyEnv）作为别名被接受。如果同时设置了 key_env 和 AZURE_ANTHROPIC_KEY/ANTHROPIC_API_KEY，以 key_env 命名的环境变量优先。

模型发现

Azure 不会暴露一个纯 API 密钥端点来列出你已部署的模型部署。部署枚举需要 Azure Resource Manager 认证（az cognitiveservices account deployment list）配合 Azure AD 主体，而非推理 API 密钥。

Hermes 可以做到的：

• Azure OpenAI v1 端点（<resource>.openai.azure.com/openai/v1）通过 GET /models 暴露资源的可用模型目录。Hermes 使用此列表预填充模型选择器。
• Azure Foundry /anthropic 路由：通过 URL 路径检测，模型名称需手动输入。
• 私有/防火墙后的端点：手动输入，并显示友好的"无法探测"提示。

你始终可以直接输入部署名称 — Hermes 不会对返回的列表进行验证。

环境变量

故障排除

gpt-5.x 部署返回 401 Unauthorized。 Azure 在 /chat/completions 上提供 gpt-5.x，而非 /responses。当 URL 包含 openai.azure.com 时，Hermes 会自动处理此情况。但如果你看到带有 Invalid API key 正文的 401 错误，请检查 config.yaml 中的 api_mode 是否为 chat_completions。

/v1/messages?api-version=.../v1/messages 返回 404。 这是修复前 Azure Anthropic 配置中的 URL 畸形 bug。请升级 Hermes — api-version 参数现在通过 default_query 传递，而非写入 base URL，SDK 在 URL 拼接时不会再破坏它。

向导显示 "Auto-detection incomplete."。 端点拒绝了 /models 探测和 Anthropic Messages 探测。对于防火墙后或有 IP 白名单的私有端点，这是正常现象。回退到手动 API 模式选择并输入部署名称 — 一切仍然正常工作，Hermes 只是无法预填充选择器。

选错了传输协议。 重新运行 hermes model，向导会重新探测。如果探测仍然选错模式，你可以直接编辑 config.yaml：

model:
  provider: azure-foundry
  api_mode: anthropic_messages   # or chat_completions