Installation

Install Extended OpenAI Conversation via HACS or manually

Prerequisites

• Home Assistant instance
• API key for your chosen provider (or any placeholder value for local servers)

Installation Methods

HACS (Recommended)

Install via HACS

1. Install integration

   1. Click the button above or open HACS in Home Assistant
   2. Go to “Integrations”
   3. Click ”+ Explore & Download Repositories”
   4. Search for “Extended OpenAI Conversation”
   5. Click “Download”
   6. Restart Home Assistant

Manual Installation

Manual Installation

1. Download files

   Download the extended_openai_conversation folder from the repository

2. Copy to custom_components

   Copy the folder to <config directory>/custom_components/

   Your directory structure should look like:

   <config>/
   └── custom_components/
       └── extended_openai_conversation/
           ├── __init__.py
           ├── manifest.json
           └── ...
   
3. Restart

   Restart Home Assistant

Setup

1. Add integration

   1. Click the button above or go to Settings > Devices & Services
   2. Click Add Integration button (bottom right)
   3. Search for “Extended OpenAI Conversation”
   4. Follow the setup wizard
2. Choose provider and enter credentials

   Select your API Provider and fill in the required fields.

   See the Provider Setup section below for provider-specific values.

3. Configure voice assistant

   1. Go to Settings > Voice Assistants
   2. Click to edit your Assistant (named “Home Assistant” by default)
   3. Select Extended OpenAI Conversation from the “Conversation agent” dropdown

   

Provider Setup

OpenAI

OpenAI

The default provider. Requires a valid OpenAI API key.

Field	Value
API Provider	OpenAI
Base URL	https://api.openai.com/v1 (default)
API Key	Your OpenAI API key
Skip Authentication	Off

Get your API key from platform.openai.com/api-keys.

Recommended models: gpt-4o-mini (balanced), gpt-4o (capable), gpt-5-mini (default)

Reasoning models (o1, o3, o4, gpt-5) do not support temperature or top_p. Those fields are hidden automatically and replaced with Reasoning Effort.

Azure OpenAI

Azure OpenAI

Requires an Azure AI Foundry project with a deployed model.

Field	Value
API Provider	Azure OpenAI
Base URL	https://xxxxxxxxx.cognitiveservices.azure.com/
API Key	Your Azure API key
API Version	e.g. 2024-12-01-preview
Skip Authentication	On

1. Create an Azure OpenAI resource

   In Azure Portal, create an Azure OpenAI resource if you haven’t already.

2. Open Azure AI Foundry and find your model endpoint

   1. Go to Azure AI Foundry
   2. Navigate to My Assets → Models + endpoints
   3. Select the model you want to use
   4. Open the Code tab in the model detail view
3. Copy credentials from the code example

   From the code example, copy these three values:

   • azure_endpoint → use as Base URL (e.g. https://xxxxxxxxx.cognitiveservices.azure.com/)
   • api_version → use as API Version (e.g. 2024-12-01-preview)
   • API key shown in the example → use as API Key
4. Configure the integration

   • Set API Provider to Azure OpenAI
   • Paste the values copied above into the corresponding fields
   • Enable Skip Authentication
5. Set the model name

   In the assistant options, enter the model name that is deployed in the Models + endpoints list.

Azure API Management domains (azure-api.net, services.ai.azure.com) are also supported in addition to cognitiveservices.azure.com.

Other Compatible Servers

Other OpenAI-Compatible Servers

Any server that implements the OpenAI-compatible API (Ollama, LM Studio, Groq, etc.) can be used.

General configuration:

Field	Value
API Provider	OpenAI
Base URL	http://<HOST>:<PORT>/v1
API Key	Server token, or any value if not required
Skip Authentication	On (for local servers without auth)

Server-specific notes:

Ollama

Ollama is a local model server with OpenAI-compatible API.

Field	Value
API Provider	OpenAI
Base URL	http://<HOST>:11434/v1
API Key	Any value (e.g. ollama)
Skip Authentication	On

Always enable Skip Authentication for Ollama. Without it, the integration attempts to validate your API key against Ollama’s endpoint, which can cause misleading errors during setup.

The /v1 suffix in the Base URL is required. Using http://<HOST>:11434 without /v1 causes a 404 error during setup.

Network troubleshooting:

If Ollama is unreachable from Home Assistant, verify that Ollama is bound to 0.0.0.0 and not just 127.0.0.1. Test connectivity from the HA host with:

curl http://<HOST>:11434/v1/models

qwen2.5:14b model for function calling (issue)

Many older or smaller models do not reliably emit structured tool calls. If the assistant verbally acknowledges your request but nothing actually happens, add this to your system prompt:

When you want to take action, you MUST use the execute_services function.
You must wrap your commands in a list array.

LM Studio

LM Studio exposes an OpenAI-compatible local API.

Field	Value
API Provider	OpenAI
Base URL	http://<HOST>:1234/v1
API Key	Any value (e.g. lm-studio)
Skip Authentication	On

The default port is 1234. Adjust the host/port if running LM Studio on a different machine or port.

Model name: Enter the model identifier shown in LM Studio’s loaded model list (e.g. qwen2.5-7b-instruct).

The same function-calling limitations and prompt engineering tips that apply to Ollama also apply to LM Studio. Use models explicitly trained for tool use.

Groq

Groq provides a cloud API with OpenAI-compatible endpoints.

• Base URL: https://api.groq.com/openai/v1
• API Key: Your Groq API key from console.groq.com
• Skip Authentication: Off

Mistral AI

Mistral’s API uses shorter tool call IDs. Enable Shorten Tool Call ID in Advanced Options to avoid errors.

• Base URL: https://api.mistral.ai/v1
• Advanced Options: Enable Shorten Tool Call ID

Universal checklist for local/compatible servers:

1. Base URL must end with /v1
2. Enable Skip Authentication for any server that doesn’t validate API keys
3. Function calling is model-dependent — prefer models trained for tool use
4. Prompt engineering helps with local models — instruct the model explicitly to call execute_services and wrap commands in {"list": [...]}

Expose Entities

You must expose entities for the AI to control them. Without exposed entities, the assistant won’t know what devices are available.

1. Navigate to: http://{your-home-assistant}/config/voice-assistants/expose
2. Select entities you want the AI to control
3. Enable the toggle for each entity

Verify Installation

Test your setup by asking the assistant a simple question:

"What lights are available?"

If configured correctly, the assistant should respond with a list of your exposed light entities.

Next Steps

Configuration

Customize options and behavior

Functions

Learn about function types