diff --git a/docs/core/conversation/custom_agent.md b/docs/core/conversation/custom_agent.md new file mode 100644 index 00000000..f8c66e56 --- /dev/null +++ b/docs/core/conversation/custom_agent.md @@ -0,0 +1,53 @@ +--- +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. + +```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): + """Return the attribution.""" + return { + "name": "My Conversation Agent", + "url": "https://example.com", + } + + @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 | None: + """Process a sentence.""" + response = intent.IntentResponse(language=language) + response.async_set_speech("Test response") + return agent.ConversationResult( + conversation_id=None, + response= + ) +``` diff --git a/docs/voice/overview.md b/docs/voice/overview.md index 1a1a505d..5fad5901 100644 --- a/docs/voice/overview.md +++ b/docs/voice/overview.md @@ -27,7 +27,7 @@ graph TD; ``` - The **Voice Assistant** integration is responsible for turning the user's speech into text, get it processed, and turn the response into speech. _This integration has not been created yet._ - - The **Conversation** integration is responsible for processing user's text. It does this by matching it to an intent. + - 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 **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. diff --git a/sidebars.js b/sidebars.js index e62e080e..932b8703 100644 --- a/sidebars.js +++ b/sidebars.js @@ -205,6 +205,7 @@ module.exports = { "creating_integration_brand", "core/platform/application_credentials", "core/platform/backup", + "core/conversation/custom_agent", "core/platform/repairs", "core/platform/reproduce_state", "core/platform/significant_change",