From e09bd746143d62e7538aa6e27f4a974f962728eb Mon Sep 17 00:00:00 2001
From: Paulus Schoutsen <balloob@gmail.com>
Date: Wed, 16 Jul 2025 09:07:07 +0200
Subject: [PATCH] Document AI task (#2717)

Co-authored-by: Allen Porter <allen@thebends.org>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---
 docs/core/entity/ai-task.md | 103 ++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 docs/core/entity/ai-task.md

diff --git a/docs/core/entity/ai-task.md b/docs/core/entity/ai-task.md
new file mode 100644
index 00000000..0353152f
--- /dev/null
+++ b/docs/core/entity/ai-task.md
@@ -0,0 +1,103 @@
+---
+title: AI Task entity
+sidebar_label: AI Task
+---
+
+An AI Task entity provides a framework for AI-powered task execution in Home Assistant. It enables integrations to offer AI capabilities for generating data, content, or performing structured tasks based on natural language instructions.
+
+A AI Task entity is derived from the [`homeassistant.components.ai_task.AITaskEntity`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/ai_task/entity.py). The entity state tracks the timestamp of the last activity for monitoring purposes.
+
+## Properties
+
+_This entity has no properties._
+
+## Supported features
+
+Supported features are defined by using values in the `AITaskEntityFeature` enum and are combined using the bitwise or (`|`) operator.
+
+| Value | Description
+| ----- | -----------
+| `GENERATE_DATA` | The entity can generate data based on natural language instructions.
+
+## Methods
+
+### Generate Data
+
+This method handles data generation tasks based on natural language instructions.
+
+```python
+from homeassistant.components.ai_task import AITaskEntity, GenDataTask, GenDataTaskResult
+
+class MyAITaskEntity(AITaskEntity):
+    """Represent an AI Task entity."""
+
+    async def _async_generate_data(
+        self, task: GenDataTask, chat_log: ChatLog
+    ) -> GenDataTaskResult:
+        """Handle a generate data task."""
+        # Process the task instructions and generate appropriate data
+        # Use the chat_log to maintain conversation context. A common
+        # pattern is to share an implementation between conversation and AI
+        # task entities to process the chat log.
+        # await self._async_handle_chat_log(
+        #  chat_log,
+        #  task.structure,
+        #  task.attachments
+        # )
+
+        text = ...
+        if not task.structure:
+            return GenDataTaskResult(
+                conversation_id=chat_log.conversation_id,
+                data=text
+            )
+
+        data = ... # process the text to match the structure
+        return GenDataTaskResult(
+            conversation_id=chat_log.conversation_id,
+            data=data
+        )
+
+```
+
+A `GenDataTask` object contains the following data:
+
+| Name | Type | Description
+| ---- | ---- | -----------
+| `task_name` | `str` | Name/identifier for the task
+| `instructions` | `str` | Natural language instructions for the AI
+| `structure` | `vol.Schema` \| `None` | Optional schema for structured output validation
+| `attachments` | `list[PlayMediaWithId]` | List of attachments to include in the task.
+
+## Structured Output Schema
+
+The `structure` parameter allows you to define the expected format of the generated data using Home Assistant's [selector system](https://www.home-assistant.io/docs/blueprint/selectors/):
+
+```python
+{
+    "yes_no_field": {
+        "description": "Description of the field",
+        "required": True/False,  # Optional, defaults to False
+        "selector": {
+            "boolean": {}  # Selector type
+        }
+    },
+    "text_field": {
+        "description": "Description of the text field",
+        "required": True/False,  # Optional, defaults to False
+        "selector": {
+            "text": {}  # Selector type
+        }
+    },
+    "number_field": {
+        "description": "Description of the number field",
+        "required": True/False,  # Optional, defaults to False
+        "selector": {
+            "number": {
+                "min": 18,  # Optional minimum value
+                "max": 100,  # Optional maximum value
+            }
+        }
+    },
+}
+```