Skip to main content

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 and intent handlers.

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:

textstrUser input
contextContextHA context to attach to actions in HA
conversation_idOptional[str]Can be used to track a multi-turn conversation. Return None if not supported
languagestrLanguage of the text. If user did not provide one, it's set to the HA configured language.
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):

def attribution(self) -> agent.Attribution:
"""Return the attribution."""
return {
"name": "My Conversation Agent",
"url": "",

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(