mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-04-19 10:57:14 +00:00
Add converation entity docs (#2132)
* Add converation entity docs * Fix links
This commit is contained in:
Paulus Schoutsen
GitHub
parent
81069b1868
commit
3ce212327c
@ -5,7 +5,7 @@ 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.
|
||||
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/entity/conversation) 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)
|
||||
|
||||
@ -1,49 +0,0 @@
|
||||
---
|
||||
title: Conversation Agent
|
||||
---
|
||||
|
||||
The conversation integration offers a standardized API for users to use human speech to interact with Home Assistant. The actual processing of human speech is handled by a conversation agent.
|
||||
|
||||
The integration provides a default conversation agent that uses our own [intent recognizer](../../voice/intent-recognition) and [intent handlers](../../intent_index).
|
||||
|
||||
## Creating 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
|
||||
from homeassistant.components.conversation import agent
|
||||
|
||||
|
||||
async def async_setup(hass, config):
|
||||
"""Initialize your integration."""
|
||||
conversation.async_set_agent(hass, MyConversationAgent())
|
||||
|
||||
|
||||
class MyConversationAgent(agent.AbstractConversationAgent):
|
||||
|
||||
@property
|
||||
def attribution(self) -> agent.Attribution:
|
||||
"""Return the attribution."""
|
||||
return {
|
||||
"name": "My Conversation Agent",
|
||||
"url": "https://example.com",
|
||||
}
|
||||
|
||||
@abstractmethod
|
||||
async def async_process(self, user_input: agent.ConversationInput) -> agent.ConversationResult:
|
||||
"""Process a sentence."""
|
||||
response = intent.IntentResponse(language=user_input.language)
|
||||
response.async_set_speech("Test response")
|
||||
return agent.ConversationResult(
|
||||
conversation_id=None,
|
||||
response=response
|
||||
)
|
||||
```
|
||||
59
docs/core/entity/conversation.md
Normal file
59
docs/core/entity/conversation.md
Normal file
@ -0,0 +1,59 @@
|
||||
---
|
||||
title: Conversation Entity
|
||||
sidebar_label: Conversation
|
||||
---
|
||||
|
||||
A conversation entity allows users to converse with Home Assistant.
|
||||
|
||||
A conversation entity is derived from the [`homeassistant.components.conversation.ConversationEntity`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/conversation/entity.py).
|
||||
|
||||
## Properties
|
||||
|
||||
:::tip
|
||||
Properties should always only return information from memory and not do I/O (like network requests).
|
||||
:::
|
||||
|
||||
| Name | Type | Default | Description
|
||||
| ---- | ---- | ------- | -----------
|
||||
| supported_languages | `list[str]` \| `Literal["*"]` | **Required** | The supported languages of the service. Return `"*"` if you support all.
|
||||
|
||||
## Methods
|
||||
|
||||
### Process
|
||||
|
||||
This method is used to process an incoming chat message.
|
||||
|
||||
```python
|
||||
class MyConversationEntity(ConversationEntity):
|
||||
"""Represent a conversation entity."""
|
||||
|
||||
async def async_process(self, user_input: ConversationInput) -> ConversationResult:
|
||||
"""Process a sentence."""
|
||||
response = intent.IntentResponse(language=user_input.language)
|
||||
response.async_set_speech("Test response")
|
||||
return agent.ConversationResult(
|
||||
conversation_id=None,
|
||||
response=response
|
||||
)
|
||||
```
|
||||
|
||||
A `ConversationInput` object 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.
|
||||
|
||||
### Prepare
|
||||
|
||||
As soon as Home Assistant knows a request is coming in, we will let the conversation entity prepare for it. This can be used to load a language model or other resources. This function is optional to implement.
|
||||
|
||||
```python
|
||||
class MyConversationEntity(ConversationEntity):
|
||||
"""Represent a conversation entity."""
|
||||
|
||||
async def async_prepare(self, language: str | None = None) -> None:
|
||||
"""Prepare a language for processing."""
|
||||
```
|
||||
@ -27,10 +27,10 @@ graph TD;
|
||||
```
|
||||
|
||||
- The **Assist Pipeline** integration is responsible for turning the user's speech into text, get it processed, and turn the response into speech.
|
||||
- The **Conversation** integration is responsible for processing user's text. The built-in conversation agent does this by matching it to an intent. Integrations can provide [custom conversation agents](../core/conversation/custom_agent).
|
||||
- The **Conversation** integration is responsible for processing user's text. The built-in conversation agent does this by matching it to an intent. Integrations can provide [custom conversation agents](../core/entity/conversation).
|
||||
- The **Intent** integration is responsible for executing the intent and returning a response.
|
||||
- The **Text-to-Speech** integration is responsible for turning text into speech.
|
||||
- The **Speech-to-Text** integration is responsible for turning speech into text.
|
||||
- The **Text-to-Speech** integration is responsible for turning text into speech. Integrations can provide [custom text-to-speech agents](../core/entity/tts).
|
||||
- The **Speech-to-Text** integration is responsible for turning speech into text. Integrations can provide [custom speech-to-text agents](../core/entity/stt).
|
||||
|
||||
## Capturing the user's speech
|
||||
|
||||
|
||||
@ -203,7 +203,7 @@ module.exports = {
|
||||
{
|
||||
type: "category",
|
||||
label: "Conversation",
|
||||
items: ["intent_conversation_api", "core/conversation/custom_agent"],
|
||||
items: ["intent_conversation_api"],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
|
||||
@ -65,7 +65,7 @@
|
||||
/docs/reproduce_state_index /docs/core/platform/reproduce_state
|
||||
/docs/significant_change_index /docs/core/platform/significant_change
|
||||
/docs/supervisor/developing /docs/supervisor/development
|
||||
|
||||
/docs/core/conversation/custom_agent /docs/core/entity/conversation
|
||||
|
||||
# Tidying moved pages
|
||||
/docs/creating_platform_example_sensor https://github.com/home-assistant/example-custom-config/tree/master/custom_components/example_sensor
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user