xAI Conversation

Bringing the power of xAI Grok to your Home Assistant.

---

Conversation Agent

A complete conversation agent integration for Home Assistant that offers multiple ways to manage your conversation data and interact with your smart home through Grok.

---

🚀 Installation

Via HACS (Recommended)

1. Open HACS in Home Assistant.
2. Search for "xAI Conversation" and click Download.
3. Restart Home Assistant.
4. Go to Settings → Devices & Services → Add Integration → xAI Conversation.
5. Enter your xAI API key (get one at x.ai).

---

✨ Key Features

Feature	Description
Conversation Continuity	When using Server-side Memory, chats continue seamlessly across any device configured with your user account (Smartphone, Tablet, PC, etc.).
Location Context	Set your home location (e.g., "Rome, IT") to help Grok with local searches like weather and news. Leave empty to use the Home Assistant time zone instead.
User Recognition	Enable "Include username in messages" so Grok can identify and address you personally by your person entity name (or user display name as fallback).

🔄 Operational Modes

Select the best balance between privacy, cost, and efficiency:

Mode	Memory Location	Privacy	Cost	Best For
Server-side Memory (default)	xAI Cloud	Standard	Lowest	Efficiency, speed, and long-running conversations.
Zero Data Retention (ZDR)	Local blob (Encrypted)	Maximum	Medium	Privacy-focused context preservation (requires reasoning model).
Local Chatlog	Home Assistant	Standard	Highest	Full local history control with stateless turn-by-turn processing.

NOTE

• Automatic Model Selection: When ZDR is enabled, the integration automatically selects a compatible reasoning model to correctly re-initialize the conversation from encrypted state blobs.
• Local Chatlog is active when both Server-side Memory and Zero Data Retention are disabled.

🛠️ Interaction Modes

Grok acts as an advanced ASR/NLU orchestrator, providing three distinct ways to interact with your Home Assistant instance:

Mode	Description
Intelligent Pipeline (Default)	Leverages the Home Assistant Intent Pipeline. Works flawlessly with official and custom intents. Automatically falls back to Tool Control if needed to guarantee a premium experience.
Tool Control	Direct interaction via Tool Calling. Use Home Assistant Standard Tools or Extended Tools (YAML).
Chat Only	A pure conversational experience. Chat with Grok for general knowledge or assistance without interacting with Home Assistant entities.

NOTE

• In the configuration agent options:

  • Intelligent Pipeline: Enabled by default, requires "Allow smart home control" to be ON.
  • Tool Control: Active when "Allow smart home control" is ON and "Enable Intelligent Pipeline" is OFF.
  • Chat Only: Active when "Allow smart home control" is OFF.

• Switching between these modes starts a new conversation with a separate history.

• The configuration page may automatically reload when toggling certain options (like Operational Modes, Zero Data Retention, or Memory Settings) to correctly apply internal logic and dynamic fields. This is expected behavior.

🔧 Extra Tools

Extended Tools (YAML)

This component supports custom tools in YAML format, fully compatible with Extended OpenAI Conversation. Enable and configure them in the integration's global configuration settings, then activate them per conversation agent settings.

Home Assistant Extended Tools

This integration extends the standard Home Assistant tools with additional capabilities for controlling helpers, scripts, and automations. These tools are automatically available when "Allow smart home control" is enabled and you are using the standard Home Assistant tools.

Tool	Description
HassSetInputNumber	Sets the value of an input_number entity (volume, temperature, etc.)
HassSetInputBoolean	Turns an input_boolean entity on or off (toggles, flags)
HassSetInputText	Sets the text value of an input_text entity
HassRunScript	Executes a Home Assistant script
HassTriggerAutomation	Triggers a Home Assistant automation
HassPhotoAnalysis	Have them describe to you what your cameras see
IntentExecution	Your custom intents become tools!

xAI Tools

Enable Live Search (web) and 𝕏 Search in the conversation agent options for real-time information with citations (if you enable citations in the conversation agent options).

---

Stateless data generation

⚙️ AI Task Integration

Stateless data generation, smart automations, and image generation.

💭 ASK (xai_conversation.ask)

A highly versatile, stateless service designed for one-shot queries. Similar to AI Task, it doesn't maintain history, but it allows you to override the model, temperature, and live search settings "on the fly" for each individual call. It returns the response directly in a variable.

Use Case: Ideal for processing raw sensor data, distilling information from the web, or any task that requires a specific Grok model different from your default assistant.

service: xai_conversation.ask
data:
  instructions: "{{ instructions }}"
  input_data: "{{ data_to_send }}"
  model: grok-4-1-fast-non-reasoning  # (optional)
  temperature: 0.7  # (optional)
  max_tokens: 1000  # (optional)
  reasoning_effort: "low"  # (optional) - for reasoning models
  live_search: "web search"  # (optional) - web search, x search, or full
  show_citations: true  # (optional)
response_variable: output_xai

📸 Photo Analysis (xai_conversation.photo_analysis)

A stateless vision service to analyze snapshots or external images. Similarly to the ask service, it is fully configurable per call and can be integrated into Automations, Scripts, or used for manual inspection via Developer Tools.

service: xai_conversation.photo_analysis
data:
  prompt: "Is there a package at the front door?"
  images:
    - /config/www/doorbell_snapshot.jpg
  temperature: 0.1  # (optional)
  top_p: 1.0        # (optional)

---

🔧 Maintenance

Services and Sensors for model, price cost, system health, resetting stats, or clearing history.

📊 Real-time Monitoring

Detailed sensors for:

• model costs
• token counts
• cache efficiency
• xAI Server tool invocations
• notifications for new model releases.

🛠️ Manage Sensors

Forcefully refresh data or reset counters. Primarily used via Developer Tools or triggered by Automations.

service: xai_conversation.manage_sensors
data:
  reload_pricing: true #(or false) - Force update models and pricing from xAI
  reset_stats: false #(or true) - Reset all token and cost sensors to zero

🧹 Clear Memory

Clear conversation history for specific users or devices. Use it in Developer Tools for maintenance or triggered by Automations.

service: xai_conversation.clear_memory
data:
  user_id: person.admin  # Clear memory for a specific person
  include_server: true   # Also delete history from xAI servers

---

⚠️ Deprecation Notice: Grok Code Fast

The Grok Code Fast service and the associated card are now unsupported (available up to release v2.2.1).

We recommend moving to the new and much more powerful AI Code Task integration:

AI Code Task is an agnostic simple IDE provider in a Lovelace card for code generation. It provides a superior workflow for modifying and generating YAML, Jinja2 templates, Python scripts, and more with an integrated pro editor.

🤝 Contributing & Support

• 🐛 Bugs: GitHub Issues

• 💡 Feature Request: GitHub Issues

• 📖 Documentation: Wiki (coming soon)

• ⭐ Love this project? Give it a star to show your support!

  

Legal Notes

• This is a custom component for Home Assistant developed by @pajeronda

• This custom component is released under the GNU General Public License v3.0

• This custom component uses the official xAI Python SDK

• API Usage: This custom component requires an active xAI account and a valid API key. Use of the xAI API is subject to xAI's terms of service.

• Trademarks: xAI, Grok, and related logos are registered trademarks of xAI Corp. This custom component is an unofficial integration for Home Assistant and is not affiliated with, sponsored by, or endorsed by xAI Corp.