Document custom conversation agent (#1628)

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=
+        )
+```

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.

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