mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-13 20:36:29 +00:00
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 <hansen.mike@gmail.com> Co-authored-by: Michael Hansen <hansen.mike@gmail.com>
This commit is contained in:
parent
adbd3ba9ce
commit
5b2815e5a4
15
blog/2023-01-24-conversation-updates.md
Normal file
15
blog/2023-01-24-conversation-updates.md
Normal 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.
|
@ -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,
|
||||
|
Loading…
x
Reference in New Issue
Block a user