Exposing scripts to conversation agents that use AI
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] that uses AI can run your scriptsA script is a saved list of steps that runs when you start it, for example, from a dashboard, with Assist, or from an automation. Unlike an automation, a script has no triggers, so it doesn’t start by itself. [Learn more]. When you expose a script to AssistThe voice assistant built into Home Assistant. You can use Assist by talking or typing in the Home Assistant web interface and in the Home Assistant Companion app. You can also use it by talking through a voice satellite. You can set up several assistants, each with its own language and conversation agent. [Learn more], the script 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. The conversation agent can then run the script directly, if Device control is selected in its AI tools option. AI appsThird-party software that connects to Home Assistant through the Model Context Protocol integration. An AI app can use the AI tools that you allow. [Learn more] that use the Device control set through the Model Context Protocol Server can run it too. If you turn on Read-only in the options of that server, its main URL leaves scripts out.
This is more powerful than exposing entities, but it needs a good description. Without one, the conversation agent doesn’t know what the script does or when to use it.
This page explains how to expose a script, and how to describe it so that the conversation agent uses it reliably.
Exposing a script to Assist
Exposed scriptsA script is a saved list of steps that runs when you start it, for example, from a dashboard, with Assist, or from an automation. Unlike an automation, a script has no triggers, so it doesn’t start by itself. [Learn more] don’t appear in the list of entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] that the 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] gets. They appear as 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] instead.
To expose a script to Assist:
- Go to Settings > Automations & scenes > Scripts and select the script.
- Select Menu
> Settings. - Select Voice assistants.
- Under Expose, turn on Assist.
- Result: The change takes effect right away.
- Repeat these steps for each script that you want the conversation agent to use.
Some AI services limit how many AI tools a conversation agent can use at once. This number includes all AI tools, not only your scripts. If you expose many scripts, check the limits of your AI service.
Adding a description to your script
The description is the most important part of an exposed scriptA script is a saved list of steps that runs when you start it, for example, from a dashboard, with Assist, or from an automation. Unlike an automation, a script has no triggers, so it doesn’t start by itself. [Learn more]. Without a description, the 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] only gets the name of the 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], which is based on the entity ID, and the aliases of the script. By default, the aliases include the name of the script. That’s often not enough to know what the script does or when to use it.
To add or change the description of your script:
- Go to Settings > Automations & scenes > Scripts and select the script.
- Select Menu
> Rename. - The Rename dialog also contains the description.
- Enter the description in the Description field.
- If there is no Description field yet, select Add description first.
- For what to include, refer to What to write in the description.
- Keep the description short and to the point. Some AI services limit the length of the description.
- Select Rename.
- Select Save.
What to write in the description
Write a clear explanation of what the scriptA script is a saved list of steps that runs when you start it, for example, from a dashboard, with Assist, or from an automation. Unlike an automation, a script has no triggers, so it doesn’t start by itself. [Learn more] does and when the 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] should use it. Imagine you’re writing instructions for someone who knows nothing else about your home. A good description answers the following questions:
- What does this script do?
- In which situations should the conversation agent use it?
- What should the conversation agent tell you after the script runs?
For example, the Music Assistant voice support project uses the following description:
This script is used to play music based on a voice request. The tool takes the following arguments: media_type, artist, album, media_id, radio_mode, area. media_id and media_type are always required and must always be supplied as arguments to this tool. An area or Music Assistant media player can optionally be provided in the voice request as well. Use this tool whenever the user requests to play music.
Adding descriptions to script fields
If your scriptA script is a saved list of steps that runs when you start it, for example, from a dashboard, with Assist, or from an automation. Unlike an automation, a script has no triggers, so it doesn’t start by itself. [Learn more] has fields, give each field its own description. The 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] uses these descriptions to decide which value to pass. If a field has no description, the conversation agent only gets the field key and the name of the field.
In the script editor, the description of a field is called a note.
To add descriptions to script fields:
- Go to Settings > Automations & scenes > Scripts and select the script.
- Under Fields, select Menu
> Add note on the field. - If the field already has a note, the menu shows Edit note instead.
- Enter the description in the Note field.
- Keep it short and precise. Say what the field represents, which format it expects, and which values are allowed.
- Select Submit.
- Select Save.
Returning a result from your script
When the 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] runs a scriptA script is a saved list of steps that runs when you start it, for example, from a dashboard, with Assist, or from an automation. Unlike an automation, a script has no triggers, so it doesn’t start by itself. [Learn more], it gets the response of the script. If the script has no response, the conversation agent gets an empty result. It then can’t tell what happened, and it might make up an answer.
To return a result from your script:
-
Before the end of the script, store the result in a variable. Do one of the following:
-
If an actionAn action makes Home Assistant do something, for example, turn on a light, send a notification, or activate a scene. Automations and scripts run a list of actions. [Learn more] in the script returns data, enter a name in the Response variable of that action.
-
Otherwise, add a Define variables action. It opens in YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the
configuration.yamlorautomations.yamlfiles. [Learn more]. Undervariables, enter a variable with keys and values. A variable with only text doesn’t work. For example, withresult: "done", the conversation agent gets an error instead of the result. This example works:variables: result: temperature: "{{ states('sensor.outdoor_temperature') }}"
-
-
At the end of the script, add a Stop action.
-
In The name of the variable to use as response, enter the name of that variable.
- To tell the conversation agent that something went wrong, leave Stop because of an unexpected error off. Describe the problem in the variable instead.
-
Select Save.
- Result: The conversation agent gets the content of that variable.
The text in Reason for stopping doesn’t reach the conversation agent. It only appears in the trace of the script. If you turn on Stop because of an unexpected error, the conversation agent gets an empty result. In that case, Home Assistant ignores the response variable.
Checking that the conversation agent uses your script
Scripts don’t appear in the list of entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] that the 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] gets. To check that the conversation agent can use your scriptA script is a saved list of steps that runs when you start it, for example, from a dashboard, with Assist, or from an automation. Unlike an automation, a script has no triggers, so it doesn’t start by itself. [Learn more], ask it to do something that the script does.
Prerequisites:
- A conversation agent that uses AI. To add one, set up an AI integration. Examples are OpenAI and Google Gemini.
- An assistant that uses this conversation agent.
- Device control is selected in the AI tools option of the conversation agent.
- The script is exposed to Assist.
- Prefer handling commands locally is turned off in the assistantA configuration of Assist with its own name, language, and conversation agent. An assistant can also use speech-to-text to understand spoken commands and text-to-speech to reply out loud., at least while you test. Otherwise, the built-in conversation agent might run the script itself, without 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].
To check that the conversation agent uses your script:
- On a dashboard, in the top-right corner, select Assist
. - On a narrow screen, it’s under Menu
. On a computer, you can also press A.
- On a narrow screen, it’s under Menu
- At the top of the dialog, select the name of the assistant, and choose the assistant that uses your conversation agent.
- Ask for something that the script should do.
- Above the answer, select Show details.
- Result: The details list the AI tools that the conversation agent used, with the values it passed and the result it got back. Your script appears as
script__followed by the part of its entity ID afterscript.. Its result contains the content of the response variable of the script. - For example,
script.play_musicappears asscript__play_music. - If Show details is missing, the conversation agent didn’t use any AI tools, so it didn’t run your script. In that case, check the description of the script.
- Result: The details list the AI tools that the conversation agent used, with the values it passed and the result it got back. Your script appears as