diff --git a/source/_docs/scripts.markdown b/source/_docs/scripts.markdown index f9f2097b039..804849270f1 100644 --- a/source/_docs/scripts.markdown +++ b/source/_docs/scripts.markdown @@ -823,7 +823,8 @@ Some of the caveats of running actions in parallel: ## Stopping a script sequence -It is possible to halt a script sequence at any point. Using the `stop` action. +It is possible to halt a script sequence at any point and return script responses +using the `stop` action. The `stop` action takes a text as input explaining the reason for halting the sequence. This text will be logged and shows up in the automations and @@ -836,6 +837,15 @@ for example, a condition is not met. - stop: "Stop running the rest of the sequence" ``` +To return a response from a script, use the `response_variable` option. This +option expects the name of the variable that contains the data to return. The +response data must contains a mapping of key/value pairs. + +```yaml +- stop: "Stop running the rest of the sequence" + response_variable: "my_response_variable" +``` + There is also an `error` option, to indicate we are stopping because of an unexpected error. It stops the sequence as well, but marks the automation or script as failed to run. diff --git a/source/_posts/2023-07-05-release-20237.markdown b/source/_posts/2023-07-05-release-20237.markdown index 6387de18403..412cce55052 100644 --- a/source/_posts/2023-07-05-release-20237.markdown +++ b/source/_posts/2023-07-05-release-20237.markdown @@ -40,7 +40,7 @@ Enjoy the release! -- [Services call can now respond](#services-call-can-now-respond) +- [Services can now respond](#services-can-now-respond) - [New entity dialog for Locks](#new-entity-dialog-for-locks) - [Sentence trigger](#sentence-trigger) - [Open assist action](#open-assist-action) @@ -67,69 +67,50 @@ Don't forget to [join our release party live stream on YouTube](https://www.yout -## Services call can now respond +## Services can now respond -{% details "TODO" %} - -- Improve/extend story -- Proof read/spelling/grammar -- Replace screenshot - -Sources: - -- Add support for services to return data ([@allenporter] - [#94401]) ([google docs]) ([calendar docs]) (noteworthy) -- Allow scripts to capture service response data in variables ([@allenporter] - [#94757]) (noteworthy) -- Add return value to conversation.process service ([@balloob] - [#94740]) ([conversation docs]) (noteworthy) -- Add service response data for listing calendar events ([@allenporter] - [#94759]) ([calendar docs]) (noteworthy) -- Add service response support to dev tools (#17044) @bramkragten -- Add response variable support to service action (#17046) @bramkragten -- Add response UI to stop action (#17045) @bramkragten - -{% enddetails %} - -Services now can respond with data! 🎉 +Services can now respond with data! 🎉 Yes, you read that right! This advanced feature is a huge step forward for -Home Assistant and will allow for a lot of new possibilities. +Home Assistant and will allow for a lot of new possibilities. It is one of the +biggest fundamental changes to Home Assistant made in the past years. -So, normally, calling a service in an automation or script, is a one-way -communication to control your devices and services. For example, turning on a -light, or play an announcement on your speakers. +Calling a service in an automation or script was a one-way communication +to control your devices and services. For example, turn on a light, or make +an announcement on your speakers. So, what is the use of a service responding data? Well, it could be used to ask for information from a device or service. For example, you could ask -Home Assistant which events are on your calendar today, and and use the +Home Assistant which events are on your calendar today and use the answer from that service call to create a notification or announcement. -

- -Temporary screenshot that needs to be replaced. -

+Screenshot showing a response to a service call in the Home Assistant developers tools, listing waste pickup calendar events. -We have two brand new service to play with: +In this release, we have included two brand-new services to play with service responses: - {% my developer_call_service service="conversation.process" %} - This - service allows you to ask Assist a command or question, and get a response + service allows you to ask Assist a command or question and get a response back. - {% my developer_call_service service="calendar.list_events" %} - This service - allows you to ask Home Assistant for a list of events on your calendar. + enables you to ask Home Assistant for a list of events on your calendar. If you combine those in an automation, in the morning, you could ask -Home Assistant for todays calendar events, add things like weather information, -send it to ChatGPT using the conversation proceess and ask it to summerize it, -and send a notification to your phone with the result. +Home Assistant for today's calendar events, add things like weather information, +send it to ChatGPT using the conversation process, and ask it to summarize it +and use that response to send a notification to your phone. -[@allenporter] has put this all togther in this Blueprint to play with: +[@allenporter] has put this all together for you in +[this Blueprint](/blueprints/blog/2023-07/notify_agent_agenda.yaml): - +{% my blueprint_import badge blueprint_url="https://www.home-assistant.io/blueprints/blog/2023-07/notify_agent_agenda.yaml" %} This is just one example, but the possibilities are endless! It is exciting -to see what other creative use cases and new services with response will +to see what other creative use cases and new services with responses will be added in the future! -This feature is also added to scripts! So, you can make your scripts -respond and use that script response in your automations. This is a great way -to make your scripts more dynamic and flexible. +[This feature is also added to scripts!](/docs/scripts#stopping-a-script-sequence) +So, you can make your scripts respond and use that response in your automations. +This is a great way to make your scripts more dynamic and flexible. A special thanks to [@allenporter], who has been responsible for building out the larger part of this feature! @@ -426,7 +407,7 @@ noteworthy changes this release: [@Shulyaka]: https://github.com/Shulyaka [@vingerha]: https://github.com/vingerha [Apple TV]: /integrations/apple_tv/ -[compensation integration]: /integrations/componsation/ +[compensation integration]: /integrations/compensation/ [deep links]: /integrations/apple_tv/#launching-apps [Derivative]: /integrations/derivative/ [ESPHome]: /integrations/esphome/ diff --git a/source/blueprints/blog/2023-07/notify_agent_agenda.yaml b/source/blueprints/blog/2023-07/notify_agent_agenda.yaml new file mode 100644 index 00000000000..fe246a56ea1 --- /dev/null +++ b/source/blueprints/blog/2023-07/notify_agent_agenda.yaml @@ -0,0 +1,141 @@ +blueprint: + name: Conversation agent agenda notification + description: + Conversation agent generates a notification based on the upcoming calendar + agenda, location, and weather. + author: allenporter + domain: automation + input: + notify_time: + name: Notification time + description: Time the automation is triggered to send the notification. + selector: + time: {} + default: 07:00:00 + notify_service: + name: Notify service name + description: + The name of the notify service where the notification should be + sent. + selector: + text: {} + default: notify.notify + calendar_entity: + name: Calendar + description: The calendar entity to use for finding upcoming calendar events. + selector: + entity: + multiple: false + filter: + - domain: + - calendar + calendar_duration: + name: Calendar event duration + description: How many hours ahead to look for upcoming calendar events. + selector: + duration: + default: + hours: 18 + weather_entity: + name: Weather entity + description: The weather entity to use for upcoming weather forecast. + selector: + entity: + multiple: false + filter: + - domain: + - weather + zone_entity: + name: Home zone entity + description: + The zone entity to use to determine approximate location for understanding + typical weather. + selector: + entity: + multiple: false + filter: + - domain: + - zone + conversation_agent: + name: Conversation agent + description: |- + The conversation agent to use for generating the notification text. + This should be a OpenAI conversation agent for this Blueprint to work. + selector: + conversation_agent: + prompt: + name: Conversation agent prompt + selector: + text: + multiline: true + type: text + default: |- + Please generate text for a notification that will be sent to the users + smartphone with helpful information. + + You are a helpful personal agent that generates text for the user: + - Your answers are helpful, friendly, warm, insightful. + - Your answers are not technical, and do not include Home Assistant internal details such as entities in responses. + - Your messages help the user prepare for their day, for example: + - Making note of unusual weather for the location and time of year (but not mundane details like "0% chance of precipitation") + - How much time remaining until their first meeting + - Anything that may be special or unique, such as celebrating a birthday + +trigger: + platform: time + at: !input notify_time + +action: + - variables: + weather_entity: !input weather_entity + calendar_entity: !input calendar_entity + zone_entity: !input zone_entity + calendar_duration: !input calendar_duration + prompt: !input prompt + - alias: Fetch Calendar Agenda + service: calendar.list_events + data: + duration: !input calendar_duration + target: + entity_id: !input calendar_entity + response_variable: agenda + - alias: "Conversation Agent Notification Text" + service: conversation.process + data: + text: |- + Time: {{ now() }} + {%- if zone_entity is defined %} + Latitude: {{ state_attr(zone_entity, 'latitude') | round(1) }} + Longitude: {{ state_attr(zone_entity, 'longitude') | round(1) }} + {% endif %} + + {%- if weather_entity is defined %} + {%- set forecast = state_attr(weather_entity, 'forecast')[0] %} + {%- set temperature_unit = state_attr(weather_entity, 'temperature_unit') -%} + Weather: {{ forecast.condition }} ({{ forecast.temperature }}{{ temperature_unit }}, {{ forecast.precipitation }}% precipitation) + {%- endif %} + + Calendar "{{ state_attr(calendar_entity, 'friendly_name') }}" events for the next {{ calendar_duration.hours }}: + {%- if agenda.events %} + {%- for event in agenda.events %} + - Summary: {{ event.summary }} + Start-End: {% if event.start is defined %}{{ event.start }} to {{ event.end }}{% else %}All Day{% endif %} + {%- if event.descripton is defined %} + Descripton: {{ event.descripton }} + {% endif -%} + {%- if event.location is defined %} + Location: {{ event.location }} + {% endif -%} + {%- endfor %} + {%- else %} + - No upcoming events. + {%- endif %} + + {{ prompt }} + agent_id: !input conversation_agent + response_variable: agent + - alias: "Send notification" + service: !input notify_service + data: + title: "{{ now().strftime('%A') }} Agenda" + message: "{{ agent.response.speech.plain.speech }}" diff --git a/source/images/blog/2023-07/service-response-example.png b/source/images/blog/2023-07/service-response-example.png new file mode 100644 index 00000000000..2d3787e4f47 Binary files /dev/null and b/source/images/blog/2023-07/service-response-example.png differ