jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-25 02:06:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add blog post about breaking changes to conversation integration (#1647)

Browse Source 
* Add blog post about breaking changes to conversation integration

* Fix link

* Apply suggestions from code review

Co-authored-by: Michael Hansen <hansen.mike@gmail.com>

Co-authored-by: Michael Hansen <hansen.mike@gmail.com>
This commit is contained in:
Paulus Schoutsen 2023-01-24 22:58:45 -05:00 committed by GitHub
parent adbd3ba9ce
commit 5b2815e5a4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 26 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
blog/2023-01-24-conversation-updates.md Normal file
View File

@ -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.

26
docs/core/conversation/custom_agent.md
View File

@ -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,