{"id":7350,"library":"langchain-azure-ai","title":"LangChain Azure AI","description":"langchain-azure-ai is an integration package that provides first-class support for Azure AI Foundry capabilities within the LangChain and LangGraph ecosystems. It currently ships at version 1.2.2 and maintains an active release cadence with frequent updates and patches.","status":"active","version":"1.2.2","language":"en","source_language":"en","source_url":"https://github.com/langchain-ai/langchain-azure","tags":["langchain","azure","ai","llm","foundry","rag","microsoft"],"install":[{"cmd":"pip install -U langchain-azure-ai","lang":"bash","label":"Base installation"},{"cmd":"pip install -U \"langchain-azure-ai[tools]\"","lang":"bash","label":"For Azure AI services tools"},{"cmd":"pip install -U \"langchain-azure-ai[opentelemetry]\"","lang":"bash","label":"For OpenTelemetry tracing"},{"cmd":"pip install -U \"langchain-azure-ai[v1]\"","lang":"bash","label":"For deprecated classes from Foundry classic/Azure AI Inference SDK"}],"dependencies":[{"reason":"Core LangChain abstractions and streaming implementations require a compatible version (>=1.2 for streaming).","package":"langchain-core","optional":false},{"reason":"Required for authentication with Microsoft Entra ID and DefaultAzureCredential.","package":"azure-identity","optional":false},{"reason":"Required for creating models directly from your AI project's connection string.","package":"azure-ai-projects","optional":true},{"reason":"The core LangChain library for building chains, agents, and retrieval strategies.","package":"langchain","optional":false}],"imports":[{"symbol":"AzureAIOpenAIApiChatModel","correct":"from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel"},{"note":"This class is deprecated in favor of AzureAIOpenAIApiChatModel for OpenAI-compatible APIs. If still needed, it requires the [v1] extra and is now under `langchain_azure_ai.chat_models.inference` namespace.","wrong":"from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel","symbol":"AzureAIChatCompletionsModel","correct":"from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel"},{"note":"Recommended for authentication when using project endpoints with Microsoft Entra ID.","symbol":"DefaultAzureCredential","correct":"from azure.identity import DefaultAzureCredential"}],"quickstart":{"code":"import os\nfrom azure.identity import DefaultAzureCredential\nfrom langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel\nfrom langchain_core.messages import HumanMessage, SystemMessage\n\n# Ensure these environment variables are set\n# os.environ[\"AZURE_AI_PROJECT_ENDPOINT\"] = \"https://{your-resource-name}.services.ai.azure.com\"\n# os.environ[\"AZURE_AI_API_KEY\"] = \"your-api-key\"\n\n# Use DefaultAzureCredential for Entra ID authentication with project_endpoint\n# For API key authentication, pass 'credential=\"your-api-key\"' directly\ncredential = os.environ.get('AZURE_AI_API_KEY', DefaultAzureCredential())\n\nmodel = AzureAIOpenAIApiChatModel(\n    endpoint=os.environ.get('AZURE_AI_PROJECT_ENDPOINT', 'https://your-resource-name.services.ai.azure.com/openai/v1'),\n    credential=credential,\n    model=\"gpt-4o\" # Or your deployed model name like 'gpt-4o'\n)\n\nmessages = [\n    SystemMessage(content=\"You are a helpful translator. Translate the following from English into Italian.\"),\n    HumanMessage(content=\"I love programming.\")\n]\n\nresponse = model.invoke(messages)\nprint(response.content)\n","lang":"python","description":"This quickstart demonstrates how to initialize and use the `AzureAIOpenAIApiChatModel` for chat completions. It showcases both API key and Azure Entra ID (via `DefaultAzureCredential`) authentication methods, preferring environment variables for configuration."},"warnings":[{"fix":"Migrate to `AzureAIOpenAIApiChatModel` and `AzureAIOpenAIApiEmbeddingsModel` for new development. If using deprecated classes, install `langchain-azure-ai[v1]` and update imports to `from langchain_azure_ai.chat_models.inference import AzureAIChatCompletionsModel`.","message":"The `AzureAIChatCompletionsModel` and `AzureAIEmbeddingsModel` classes (using Azure AI Inference SDK) have been deprecated in favor of OpenAI-compatible APIs. They now reside under the `inference` sub-namespace and require the `langchain-azure-ai[v1]` extra.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Replace `project_connection_string` with `project_endpoint` when initializing models.","message":"The `project_connection_string` parameter for creating `AzureAIEmbeddingsModel` and `AzureAIChatCompletionsModel` is no longer supported. Use `project_endpoint` instead.","severity":"breaking","affected_versions":">=0.1.6"},{"fix":"Update tracing implementations to use `AzureAIOpenTelemetryTracer`. Ensure `langchain-azure-ai[opentelemetry]` is installed.","message":"The `AzureAIInferenceTracer` class has been removed. It is replaced by `AzureAIOpenTelemetryTracer` for better OpenTelemetry support and new GenAI semantic conventions.","severity":"deprecated","affected_versions":">=0.1.6"},{"fix":"Update agent creation logic to use the V2 implementation. The `AgentServiceFactory` for V1 now requires the `langchain-azure-ai[v1]` extra.","message":"Creating agents using Foundry Agents V1 (e.g., `AgentServiceFactory`) has been deprecated in favor of V2 implementation.","severity":"deprecated","affected_versions":">=1.1.0"},{"fix":"Ensure your `langchain` package is updated to at least version `1.2.13` to leverage `init_chat_model` effectively. Otherwise, configure clients directly.","message":"Using `init_chat_model(\"azure_ai:...\")` convenience method requires `langchain>=1.2.13` for full functionality, especially streaming implementations.","severity":"gotcha","affected_versions":"<1.2.13"},{"fix":"Ensure your environment is configured for Azure CLI login (`az login`) or use `DefaultAzureCredential`. Verify that the assigned identity has the 'Azure AI User' role on the Foundry project.","message":"Authentication with a `project_endpoint` (set via `AZURE_AI_PROJECT_ENDPOINT` environment variable) strictly requires Microsoft Entra ID for authentication and the 'Azure AI User' role on the project.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the `langchain-community` package: `pip install langchain-community`. Update your import statements to `from langchain_community.document_loaders import AzureAIDocumentIntelligenceLoader`.","cause":"Some Azure-related components, particularly document loaders like `AzureAIDocumentIntelligenceLoader`, were moved to `langchain-community`.","error":"ModuleNotFoundError: No module named 'langchain_community'"},{"fix":"Verify your Azure CLI login (`az login`) and ensure `DefaultAzureCredential` is correctly configured. Check that the service principal or user identity has the required Azure RBAC roles on your Azure AI resource. Also, confirm the `endpoint` and `api_version` are correct.","cause":"Incorrect or expired Azure credentials, or the assigned identity lacks the necessary permissions (e.g., 'Azure OpenAI User' or 'Cognitive Services User' role).","error":"ClientAuthenticationError: (None) Unauthorized. Access token is missing, invalid, audience is incorrect..."},{"fix":"Double-check your `endpoint` URL and `model` name against your Azure AI Studio deployments. Ensure the endpoint does not include extraneous paths. If using `project_endpoint`, only provide the root endpoint (e.g., `https://<project-name>.services.ai.azure.com/`).","cause":"The Azure OpenAI endpoint or model deployment name is incorrect or missing. This can also happen if `project_endpoint` is used incorrectly or includes extra paths like `/models/chat/completions`.","error":"openai.error.InvalidRequestError: Resource not found"},{"fix":"Migrate to `langchain_azure_ai.chat_models.AzureAIOpenAIApiChatModel` which offers better support for OpenAI-compatible APIs and structured outputs. Alternatively, use `langchain-openai` which treats Azure-compatible endpoints as OpenAI endpoints for structured output features.","cause":"The `AzureAIChatCompletionsModel` (from the deprecated inference SDK) does not fully support OpenAI-style JSON schema structured output.","error":"ValueError: Unsupported response_format {'type': 'json_schema', 'json_schema': {...}}"}]}