This is a personal fork of joselcaguilar/azure-openai-ha. See Fork Changes for what was modified.

Azure OpenAI Conversation Custom Integration for Home Assistant

Fork Changes

Changes on top of upstream (joselcaguilar/azure-openai-ha):

gpt-5.x compatibility (const.py, conversation.py)

• Default model changed from gpt-4o-mini → chat-fast (maps to gpt-4.1-nano, 100K TPM/100 req/min vs the old 10K limit)
• Web search enabled for gpt-4.1-nano and homelab deployment names (chat, chat-fast)
• gpt-5.x reasoning detection: model.startswith("o") → model.startswith(REASONING_MODEL_PREFIXES) where REASONING_MODEL_PREFIXES = ("o", "gpt-5") — prevents sending unsupported temperature/top_p/store params to gpt-5.x models (which return 400 Unsupported parameter)
• voluptuous-openapi added to requirements — HA 2026.x does not expose this core package to custom components automatically; adding it to the manifest makes HA's installer satisfy it (it detects the already-installed version and skips reinstall)

Azure homelab setup (Sweden Central, ai-homelab-swc)

Deployment	Model	TPM	Use
chat-fast	gpt-4.1-nano	100K	Default — HA voice/assist
chat	gpt-5.6-sol	50K	Advanced tasks
gpt-4o-mini	gpt-4.1-mini	10K	Legacy compat shim — do not use for HA

API Base URL: https://ai-homelab-swc.services.ai.azure.com/

---

Running Both Integrations

You can run this integration alongside Extended OpenAI Conversation — they use different HA domains so there's no conflict.

When to use which

Capability	This fork	Extended OpenAI
Voice control (lights, switches, scenes)	✅	✅
Azure Responses API + streaming	✅	❌ (Chat Completions only)
gpt-5.x support	✅	❓
Create automations via voice	❌	✅
Query entity history ("was the light on at 9am?")	❌	✅
Call external REST APIs / scrape web	❌	✅
SQLite history queries	❌	✅

Setup

1. Install Extended OpenAI Conversation via HACS

Add custom repository: jekalmin/extended_openai_conversation → Integration

Configure it with your Azure endpoint:

• API Key: same key as this integration
• Base URL: https://ai-homelab-swc.services.ai.azure.com/openai
• Model: chat-fast (or chat for advanced tasks)

⚠️ Extended uses the Chat Completions API — avoid gpt-5.x models until it adds Responses API support.

2. Create two Assistants in Home Assistant

Go to Settings → Voice Assistants → Add Assistant:

Assistant	Integration	Model	Use for
Azure Voice	This fork (Azure OpenAI Conversation)	chat-fast	Daily voice control, streaming responses
Azure Power	Extended OpenAI Conversation	chat-fast	Automations, history queries, custom functions

3. Switch between assistants

• In the Assist panel, tap the assistant name to switch
• Assign different assistants to different voice devices (e.g. phone vs. speaker)

---

What This Is

This custom integration adds a conversation agent powered by Azure OpenAI in Home Assistant, it's based on the original OpenAI Conversation integration for Home Assistant.

What It Does

This is equivalent to the built-in OpenAI Conversation integration. The difference is that it uses the OpenAI algorithms available through Azure. Other than that the goal is to keep the differences to a minimum. You can use this conversation integration with Assistants in Home Assistant to control you house. They have all the capabilities the built-in OpenAI Conversation integration has.

Limitations

Azure OpenAI Conversation Version	Home Assistant Version	Minimal API Version
0.x.y	2023.4.x	2023-06-01-preview
1.x.y	2023.5+	2023-06-01-preview
2.x.y	2025.1	2023-12-01-preview
3.1.y	2025.6	- no need to specify -
4.0.y	2025.8 - 2025.9	- no need to specify -
4.1.y	2025.10+	- no need to specify -
4.2.y	2025.12+	- no need to specify -
4.3.y	2026.2.1+	- no need to specify -
2026.09.y (this fork)	2026.9+	- no need to specify -

Installation and Configuration

Configuring Azure Models

1. Deploy an Azure AI Foundry instance to a region supported by the Responses API.
   (If you already have a Foundry instance, you can skip this step.)
2. To enable conversations, deploy a chat completion model (such as gpt-4o-mini or gpt-4.1-mini)
   If your model is not the default gpt-4o-mini, you’ll need to configure it later in step 6.
3. If you want to generate images using the generate_image service, also deploy the dall-e-3 model.

Setting Up the Integration

4. Download and install the integration from HACS: Azure OpenAI Conversation.
5. Restart your Home Assistant instance.
6. Click here or go to Settings → Devices & Services → Add Integration → Azure OpenAI Conversation.
7. Enter your API Key and API Base URL (use the format https://your-resource.services.ai.azure.com/) and hit Submit.
8. Configure your assistant to use the Azure OpenAI Conversation.

Options

Options for Azure OpenAI Conversation can be set via the user interface, by taking the following steps:

1. Browse to your Home Assistant instance.
2. In the sidebar click on Settings -> Devices & Services.
3. Find the Azure Open AI Conversation integration and click 'Configure'

Options available (same as built-in OpenAI conversation):

• Instructions: The starting text for the AI language model to generate new text from. This text can include information about your Home Assistant instance, devices, and areas and is written using Home Assistant Templating.

• Model: The name of the GPT language model deployed for text generation (i.e.- my-gpt35-model). You can find more details on the available models in the Azure OpenAI Documentation. If you are having issues using an assistant that uses this integration please check this model is the model you actually deployed.

• Maximum Tokens to Return in Response The maximum number of words or "tokens" that the AI model should generate in its completion of the prompt. For more information, see the Azure OpenAI Completion Documentation.

• Temperature: A value that determines the level of creativity and risk-taking the model should use when generating text. A higher temperature means the model is more likely to generate unexpected results, while a lower temperature results in more deterministic results. See the Azure OpenAI Completion Documentation for more information.

• Top P: An alternative to temperature, top_p determines the proportion of the most likely word choices the model should consider when generating text. A higher top_p means the model will only consider the most likely words, while a lower top_p means a wider range of words, including less likely ones, will be considered. For more information, see the Azure OpenAI Completion Documentation.

API Version change

This value couldn't be changed through options, to update it you must need to delete and recreate the integration. Make sure that you have all required values like API key saved before recreation.

Changelog

Please reference the release history.

How to Help

While it'd be nice to have more developers, you can contribute without knowing how to code. You can file bugs/feature requests, or you can help with other tasks like UI Translations and updating the README.

Getting Started (Developers)

1. Clone the repository and move into it.
2. Copy the environment template and set your GitHub token (required for HACS checks):
   • cp .env.example .env
   • set GITHUB_TOKEN in .env with read-only access to Contents and Metadata.
3. Run local checks using Docker:
   • make lint runs Ruff
   • make hassfest runs Home Assistant integration validation
   • make hacs runs HACS validation
   • make test runs all of the above
4. (Optional) Start Home Assistant locally for manual testing:
   • docker compose up -d homeassistant
   • Integration files are mounted from ./custom_components/azure_openai_conversation into the container.

UI Translations

More languages can be added here, contributions are welcome :)

Languages available:

• English

Documentation

The README file will be used for Documentation, if it's expanded in the future with automations or other tweaks, we can think on a wiki for that purpose.

Disclaimer: Don't worry about making mistakes as we can revert using the history 😊.

Funding

GitHub	Buy me a coffee

License

MIT - By providing a contribution, you agree the contribution is licensed under MIT.