2023.7: Finish service responses

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.

source/_posts/2023-07-05-release-20237.markdown

@@ -40,7 +40,7 @@ Enjoy the release!
 
 <!--more-->
 
-- [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
 
 <lite-youtube videoid="r0DLyU-4nWo" videotitle="Home Assistant 2023.7 Release Party"></lite-youtube>
 
-## 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.
 
-<p class='img'>
-<img src='https://media.discordapp.net/attachments/427516175237382144/1123597217622663278/CleanShot_2023-06-28_at_14.53.44.png?width=2422&height=1462'></a>
-Temporary screenshot that needs to be replaced.
-</p>
+<img class="no-shadow" src='/images/blog/2023-07/service-response-example.png' alt='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):
 
-<https://gist.github.com/allenporter/e70d9eb090c7dbdd593cf526e07b4abe>
+{% 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/

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 }}"