From 5b2815e5a4d63ee45fd236af8412b5936aa04a88 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Tue, 24 Jan 2023 22:58:45 -0500 Subject: [PATCH] Add blog post about breaking changes to conversation integration (#1647) * Add blog post about breaking changes to conversation integration * Fix link * Apply suggestions from code review Co-authored-by: Michael Hansen Co-authored-by: Michael Hansen --- blog/2023-01-24-conversation-updates.md | 15 ++++++++++++++ docs/core/conversation/custom_agent.md | 26 +++++++++++-------------- 2 files changed, 26 insertions(+), 15 deletions(-) create mode 100644 blog/2023-01-24-conversation-updates.md diff --git a/blog/2023-01-24-conversation-updates.md b/blog/2023-01-24-conversation-updates.md new file mode 100644 index 00000000..97b1ecb5 --- /dev/null +++ b/blog/2023-01-24-conversation-updates.md @@ -0,0 +1,15 @@ +--- +author: Paulus Schoutsen +authorURL: https://twitter.com/balloob +authorImageURL: /img/profile/paulus.jpg +title: "Future proofing the Conversation integration" +--- + +The Home Assistant 2023.2 release contains [PR 86592](https://github.com/home-assistant/core/pull/86592) and [PR 86484](https://github.com/home-assistant/core/pull/86484) which include breaking changes to [the conversation agent](/docs/core/conversation/custom_agent) API to future proof it. + +- Setting an agent now requires a config entry: `conversation.async_set_agent(hass, config_entry, agent). +- Unsetting an agent now goes via a new endpoint: `conversation.async_unset_agent(hass, config_entry) +- `AbstractConversationAgent` API has changed: + - All onboarding logic removed + - `async_process` now takes new `ConversationInput` parameter with the same arguments. Language is now always set. + - `async_process` should now always return a `ConversationResult`. It's no longer allowed to return `None` or expect error handling to be done for you. diff --git a/docs/core/conversation/custom_agent.md b/docs/core/conversation/custom_agent.md index 8905cd99..1d5de73b 100644 --- a/docs/core/conversation/custom_agent.md +++ b/docs/core/conversation/custom_agent.md @@ -8,7 +8,14 @@ The integration provides a default conversation agent that uses our own [intent ## Creating a custom conversation agent -It is possible for integrations to provide a custom conversation agent. +It is possible for integrations to provide a custom conversation agent. The `async_process` method takes a `ConversationInput` object that contains the following data: + +| Name | Type | Description +| ---- | ---- | ----------- +| `text` | `str` | User input +| `context` | `Context` | HA context to attach to actions in HA +| `conversation_id` | `Optional[str]` | Can be used to track a multi-turn conversation. Return None if not supported +| `language` | `str` | Language of the text. If user did not provide one, it's set to the HA configured language. ```python from homeassistant.helpers import intent @@ -23,7 +30,7 @@ async def async_setup(hass, config): class MyConversationAgent(agent.AbstractConversationAgent): @property - def attribution(self): + def attribution(self) -> agent.Attribution: """Return the attribution.""" return { "name": "My Conversation Agent", @@ -31,20 +38,9 @@ class MyConversationAgent(agent.AbstractConversationAgent): } @abstractmethod - async def async_process( - self, - # User input - text: str, - # The HA context to attach to actions in HA - context: Context, - # Identifier. Can be used to track a multi-turn conversation. - # Return None if not supported. - conversation_id: str | None = None, - # Language of the user input. If None, default to hass.config.language - language: str | None = None, - ) -> agent.ConversationResult: + async def async_process(self, user_input: agent.ConversationInput) -> agent.ConversationResult: """Process a sentence.""" - response = intent.IntentResponse(language=language) + response = intent.IntentResponse(language=user_input.language) response.async_set_speech("Test response") return agent.ConversationResult( conversation_id=None,