#2383·instructor

Add Azure AI Foundry as a first-class v2 provider

Author: azrirefikCreated Jun 19, 2026Updated Aug 8, 2026

Motivation

Azure OpenAI is currently usable via instructor.from_openai(AzureOpenAI(...)), but there is no dedicated from_azure() factory, no from_provider("azure/...") routing, and no AZURE_OPENAI_* environment variable auto-detection — all of which exist for other OpenAI-compatible providers like groq, perplexity, fireworks, cerebras, and xai.

Beyond ergonomics, Azure AI Foundry now hosts non-OpenAI models (Mistral, Llama, Phi, etc.) through a single endpoint. A dedicated provider would add routing value that from_openai(AzureOpenAI(...)) cannot provide — the same justification that motivated first-class providers for other OpenAI-compatible platforms.

Proposed scope

Mirror the v2 provider pattern (following PR #2306 MiniMax as the template):

  • instructor/v2/core/mode.pyAZURE_TOOLS, AZURE_JSON in Mode enum
  • instructor/v2/core/providers.pyProvider.AZURE, URL detection
  • instructor/v2/core/provider_specs.pyPROVIDER_SPECS entry
  • instructor/v2/providers/azure/handlers.pyAzureToolsHandler (extends OpenAIToolsHandler)
  • instructor/v2/providers/azure/client.pyfrom_azure() factory
  • instructor/v2/auto_client.py_build_azure() reading AZURE_OPENAI_* env
  • instructor/providers/azure/client.py — legacy compat shim
  • instructor/__init__.py — lazy import + export
  • docs/integrations/azure.md, tests/llm/test_azure/ (auto-skip without key)
  • mkdocs.yml, CHANGELOG.md, pyproject.toml (optional azure-identity dep for Entra ID)

Most files are 1-10 line shims/registry entries. Real substance = handler + client + tests + docs.

Context

  • #1692 (Entra ID support) was completed — Azure IS maintained, not rejected
  • #2039 (URL detection centralization) by @jxnl was merged — the plumbing a new provider needs is in place
  • NEW_PROVIDER_AGENT_INSTRUCTIONS.md is outdated (pre-v2); PR #2306 is the authoritative v2 template

Ask

Would a PR for this be welcome? Happy to mirror the MiniMax v2 pattern. If there's a preference for scope (e.g., Azure OpenAI only vs. full Foundry routing), I can adjust.