Best practices with Assist
Voice control feels effortless when it is set up well, and frustrating when it is not. The good news is that getting Assist to feel natural mostly comes down to a few simple choices: which devices it can see, how things are named, and how your home is organized into areas. This page collects the small habits that make a big difference.
In Home Assistant, you decide what Assist has access to. Assist can only see and control the entities that you expose to it. There’s one exception: a conversation agentSoftware that Home Assistant uses to understand a request and decide what to do. Home Assistant has a built-in conversation agent. Integrations can add others, including ones that use AI. Conversation agents that use AI can also use AI tools. Each assistant uses a conversation agent. [Learn more] with the Home Assistant set of AI toolsA function that conversation agents and AI apps can use to read information, control entities, or manage Home Assistant. AI tools are grouped into sets. Each set provides different functionality. Some sets only work for administrators. [Learn more] selected can reach all entities. This includes entities that you never exposed or stopped exposing. For details, refer to Sets of AI tools. Home Assistant exposes common devices as you add them. Examples are lights and switches. Locks and alarm control panels stay unexposed until you expose them yourself. Garage doors and gates are covers, so Home Assistant exposes them automatically. You can change this for every entity. For details, refer to what Home Assistant exposes automatically.
Some best practices we recommend to have an efficient setup are:
Expose (the minimum) entities
Learn how in Exposing your entities to Assist.
Home Assistant exposes some new entities to Assist automatically. If you want to decide on every entity yourself, turn off Expose new entities.
It might be tempting to expose all entities to Assist, but doing so will come with a performance penalty. The more entity names and aliases the parser will have to go through, the more time it will spend matching. And if you’re using a LLM-based conversation agent, it will incur a higher cost per request, due to the larger context size. Only expose the bare minimum you know you are going to use with voice assistants.
Check names and create aliases
Assist relies heavily on entity names, domains, and areas. Below you will find tips for tweaking these things to ensure the best experience. On top of exposing the needed data, it is worth noting that you will most likely target entities through areas and floors, like:
- Turn off the office lights
So make sure your devices and entities are correctly assigned to areas, and your areas are correctly assigned to floors. Learn how here.
Give your devices and entities short names that are easy to remember. A phrase like “Turn on Tuya Light Controller 0E54B1 Light 1” is hard to say. Name each device and entity for what it is, without the area. For example, name a light Lamp instead of Living room lamp. Assist takes the area from your sentence or from the voice satellite you’re talking to. For more tips, refer to the naming recommendations.
If you ever find yourself mentioning a certain device or entity in a certain way, make sure to add that as an alias, as it would probably be the most natural way to refer to the entity.
Names and aliases also apply to area, you need to address area names and aliases in the exact same manner as you would for entities.
Be aware of language specificity
If you have set up Home Assistant entity names in English but plan to use Assist in another language, don’t worry. You can add aliases to each entity, allowing them to be named in any language.
English has pretty simple grammar rules, but there are languages where definite articles are pre- or suffixes to words and where nouns have genders or numbers. Language leaders are making efforts to support most such declinations in each language, but they can’t control the stuff that you name. So try to think whether a certain entity having an unarticled name would be called out in a sentence requiring a definite article or vice versa. If so, add that version of the name as an alias as well.
Check domains and device classes
Assist leverages domains to define the proper verbs for the action being taken (for example, turning on/off a light, or a fan, opening/closing a cover with a door device_class, opening/closing a valve or locking/unlocking a lock.).
It might not bother anyone to have a switch.main_valve in the UI instead of a valve, but you can’t ask Assist to open the main valve if the main valve is a switch. If it was a valve.main_valve, then the former sentence would have worked without a hitch.
To prevent this, you can use either the Change device type of a switch integration or create virtual entities using template entities or Generic X, such as the generic thermostat.
The same thing applies to some device classes. For example, if you have a binary_sensor.bedroom_window with no device_class set, you can only ask whether the bedroom window is on, which doesn’t even make sense. To be able to ask if it’s open, you need to set a proper device_class to that binary_sensor, such as window.
Ready?
Once your devices and entities are correctly
- Exposed to assist
- Assigned to areas.
It is now time to speak to your device.
To talk to Assist, you can either use your phone or a custom device (and use their microphone and speaker). Check here how to do it on Android or Apple devices.
Let AI run your scripts
You can use a conversation agent that uses AI. To add one, set up an AI integration. Examples are OpenAI, Google Gemini, and Ollama for local models. Each script that you expose to Assist becomes an AI toolA function that conversation agents and AI apps can use to read information, control entities, or manage Home Assistant. AI tools are grouped into sets. Each set provides different functionality. Some sets only work for administrators. [Learn more] in the Device control set. If Device control is selected in the AI tools option of the conversation agent, it can call the script directly. Home Assistant never exposes scripts automatically, so expose the scripts that you want it to use. This is more powerful than entity exposure, but it requires a bit more care: without a good description, the conversation agent doesn’t know the script exists or when to use it.
Find out how to write these descriptions when you’re ready to expose your scripts.
Some examples to get you started
There are a few example commands to help you get started in our Sentences starter pack.
If you don’t get the right response, we recommend you check the Aliases. Sometimes, different household members may call an entity differently. You may say “TV”, whereas someone else may say “Television”
You can create aliases for exposed entities so that you can target them using different names with Assist. Aliases are available at entity, area, and floor level. Learn how in the Alias tutorial.