coder · johnstcn · Nov 11, 2025 · Oct 22, 2025 · Oct 23, 2025 · Oct 23, 2025
diff --git a/docs/ai-coder/tasks-core-principles.md b/docs/ai-coder/tasks-core-principles.md
@@ -49,19 +49,16 @@ There are two approaches to turning a Template into a Task Template:
 
 You can use a pre-existing agent module that [Coder maintains](https://registry.coder.com/modules). When using an agent module, you must define:
 
-- `coder_parameter` named _ai_prompt_: Define the AI prompt input so users can define/specify what tasks need to run
+- `coder_ai_task` resource: links a `coder_app` to a Task.
 - **Agentic Module** that defines the agent you want to use, e.g. Claude Code, Codex CLI, Gemini CLI
 
-Coder maintains various agentic modules; see [Coder Labs](https://registry.coder.com/contributors/coder-labs). These modules, in addition to defining connection information for the specific agent, reference the [AgentAPI module](https://registry.coder.com/modules/coder/agentapi) which provides connection, reporting, and agent life cycle management operations. The module also defines the `coder_ai_task` resource which allows the Task to be visible in the UI.
+Coder maintains various agentic modules; see [Coder Labs](https://registry.coder.com/contributors/coder-labs). These modules, in addition to defining connection information for the specific agent, reference the [AgentAPI module](https://registry.coder.com/modules/coder/agentapi) which provides connection, reporting, and agent life cycle management operations. The modules also output the specific `coder_app` identifier for the specific agent running inside the workspace.
 
-The following code snippet can be dropped into any existing template to modify it into a Claude-Code enabled task template. This snippet also includes space for a setup script that will prime the agent for execution.
+The following code snippet can be dropped into any existing template in Coder v2.28 or above to modify it into a Claude-Code enabled task template. This snippet also includes space for a setup script that will prime the agent for execution.
 
-```hcl
-data "coder_parameter" "ai_prompt" {
-    name = "AI Prompt"
-    type = "string"
-}
+> [!NOTE] This requires at least version 2.13.0 of the `coder/coder` Terraform provider.
 
+```hcl
 data "coder_parameter" "setup_script" {
   name         = "setup_script"
   display_name = "Setup Script"
@@ -72,12 +69,18 @@ data "coder_parameter" "setup_script" {
   default      = ""
 }
 
+data "coder_task" "me" {}
+
+resource "coder_ai_task" "task" {
+  app_id = module.claude-code.task_app_id
+}
+
 # The Claude Code module does the automatic task reporting
 # Other agent modules: https://registry.coder.com/modules?search=agent
-# Or use a custom agent: 
+# Or use a custom agent:
 module "claude-code" {
   source   = "registry.coder.com/coder/claude-code/coder"
-  version  = "3.0.1"
+  version  = "4.0.0"
   agent_id = coder_agent.example.id
   workdir  = "/home/coder/project"
 
@@ -88,7 +91,7 @@ module "claude-code" {
   claude_code_version = "1.0.82" # Pin to a specific version
   agentapi_version    = "v0.6.1"
 
-  ai_prompt = data.coder_parameter.ai_prompt.value
+  ai_prompt = data.coder_task.me.prompt
   model     = "sonnet"
 
   # Optional: run your pre-flight script
@@ -118,30 +121,32 @@ variable "anthropic_api_key" {
 
 Let's break down this snippet:
 
-- The `module "claude-code"` sets up the Task template to use Claude Code, but Coder's Registry supports many other agent modules like [OpenAI's Codex](https://registry.coder.com/modules/coder-labs/codex) or [Gemini CLI](https://registry.coder.com/modules/coder-labs/gemini)
-- Each module defines its own specific inputs. Claude Code expects the `claude_api_key` input, but OpenAI based agents expect `OPENAI_API_KEY` for example. You'll want to check the specific module's defined variables to know what exactly needs to be defined
+- The `module "claude-code"` sets up the Task template to use Claude Code. Coder's Registry supports many other agent modules like [OpenAI's Codex](https://registry.coder.com/modules/coder-labs/codex) or [Gemini CLI](https://registry.coder.com/modules/coder-labs/gemini)
+- Each module defines its own specific inputs. Claude Code expects the `claude_api_key` input, but OpenAI based agents expect `OPENAI_API_KEY` for example. You'll want to check the specific module's defined variables to know what exactly needs to be defined. You will also generally need to pass `data.coder_task.me.prompt`
+- Each module outputs the UUID of the `coder_app` related to the AI agent. In the above example, the output is named `task_app_id`. See the relevant documentation for the module for more detailed information.
 - You can define specific scripts to run before the module is installed, `pre_install_script`, or after install, `pre_install_script`. For example, you could define a setup script that calls to AWS S3 and pulls specific files you want your agent to have access to
 
 #### Using a Custom Agent
 
 Coder allows you to define a custom agent. When doing so, you must define:
 
-- `coder_parameter` named _ai_prompt_: Define the AI prompt input so users can define/specify what tasks need to run
-- `coder_ai_task` which registers the task with the UI and allows the task to be visible
-- **AgentAPI binary** which provides runtime execution logistics for the task
+- A `coder_app` resource that uses [`coder/agentapi`](https://github.com/coder/agentapi) to run the custom agent. **AgentAPI** provides runtime execution logistics for the task.
+- A `coder_ai_task` resource which associates the `coder_app` related to the AI agent with the Task.
 
-You can find the latest [AgentAPI binary here](https://github.com/coder/agentapi/releases). You can alternatively import and use the [AgentAPI module](https://registry.coder.com/modules/coder/agentapi?tab=variables) Coder maintains, which also conveniently defines the `coder_ai_task` resource.
+You can find the latest [AgentAPI binary here](https://github.com/coder/agentapi/releases). You can alternatively import and use the [AgentAPI module](https://registry.coder.com/modules/coder/agentapi?tab=variables) Coder maintains.
 
 Read more about [custom agents here](https://coder.com/docs/ai-coder/custom-agents).
 
 #### Putting it all Together
 
 Coder recommends using pre-existing agent modules when making a Task Template. Making a Task Template boils down to:
 
-1. Identify the existing agent you want access to in our [Registry](https://registry.coder.com/modules)
-1. Add the agent's module to your existing template
-1. Define the module's required inputs
-1. Define the `coder_parameter`
+1. Identify the existing agent you want access to in our [Registry](https://registry.coder.com/modules).
+1. Add the agent's module to your existing template.
+1. Define the `coder_ai_task` resource and `coder_task` data source.
+1. Wire in the module's inputs and outputs:
+    - Pass the prompt from the `coder_task` data source into the module.
+    - Pass the module's `task_app_id` output into the `coder_ai_task` resource.
 
 and you're all set to go! If you want to build your own custom agent, read up on our [Custom Agents](https://coder.com/docs/ai-coder/custom-agents) documentation.
 
@@ -163,7 +168,7 @@ These design principles aren’t just technical guidelines; they're the lens thr
 
 ### Practical Considerations
 
-Tasks don't expose template parameters at runtime, other than the AI Prompt. If users need to choose different compute, region, or tooling options for example, you can define workspace presets in the template and have users select a preset when starting the Task. See workspace presets for details: ../admin/templates/extending-templates/parameters#workspace-presets.
+Tasks don't expose template parameters at runtime. If users need to choose different compute, region, or tooling options for example, you can define workspace presets in the template and have users select a preset when starting the Task. See workspace presets for details: ../admin/templates/extending-templates/parameters#workspace-presets.
 
 ### Identity, Security, and Access
 

diff --git a/docs/ai-coder/tasks-migration.md b/docs/ai-coder/tasks-migration.md
@@ -0,0 +1,162 @@
+# Migrating Task Templates for Coder version 2.28.0
+
+Prior to Coder version 2.28.0, the definition of a Coder task was different to the above. It required the following to be defined in the template:
+
+1. A Coder parameter specifically named `"AI Prompt"`,
+2. A `coder_workspace_app` that runs the `coder/agentapi` binary,
+3. A `coder_ai_task` resource in the template that sets `sidebar_app.id`. This was generally defined in Coder modules specific to AI Tasks.
+
+Note that 2 and 3 were generally handled by the `coder/agentapi` Terraform module.
+
+The pre-2.28.0 definition will be supported until the release of 2.29.0. You will need to update your Tasks-enabled templates to continue using Tasks after this release.
+
+You can view an [example migration here](https://github.com/coder/coder/pull/20420). Alternatively, follow the steps below:
+
+## Upgrade Steps
+
+1. Update the Coder Terraform provider to at least version 2.13.0:
+
+```diff
+terraform {
+  required_providers {
+    coder = {
+      source = "coder/coder"
+-      version = "x.y.z"
++      version = ">= 2.13"
+    }
+  }
+}
+```
+
+1. Define a `coder_ai_task` resource and `coder_task` data source in your template:
+
+```diff
++data "coder_task" "me" {}
++resource "coder_ai_task" "task" {}
+```
+
+1. Update the version of the respective AI agent module (e.g. `claude-code`) to at least 4.0.0 and provide the prompt from `data.coder_task.me.prompt` instead of the "AI Prompt" parameter.
+
+```diff
+module "claude-code" {
+  source              = "registry.coder.com/coder/claude-code/coder"
+-  version             = "4.0.0"
++  version             = "4.0.0"
+    ...
+-  ai_prompt           = data.coder_parameter.ai_prompt.value
++  ai_prompt           = data.coder_task.me.prompt
+}
+```
+
+1. Add the `coder_ai_task` resource and set `app_id` to the `task_app_id` output of the Claude module.
+
+> [!NOTE] Refer to the documentation for the specific module you are using for the exact name of the output.
+
+```diff
+resource "coder_ai_task" "task" {
++ app_id = module.claude-code.task_app_id
+}
+```
+
+## Coder Tasks format pre-2.28
+
+Below is a minimal illustrative example of a Coder Tasks template pre-2.28.0.
+**Note that this is NOT a full template.**
+
+```hcl
+terraform {
+  required_providers {
+    coder = {
+      source = "coder/coder
+    }
+  }
+}
+
+data "coder_workspace" "me" {}
+
+resource "coder_agent" "main" { ... }
+
+# The prompt is passed in via the specifically named "AI Prompt" parameter.
+data "coder_parameter" "ai_prompt" {
+  name    = "AI Prompt"
+  mutable = true
+}
+
+# This coder_app is the interface to the Coder Task.
+# This is assumed to be a running instance of coder/agentapi
+resource "coder_app" "ai_agent" {
+  ...
+}
+
+# Assuming that the below script runs `coder/agentapi` with the prompt
+# defined in ARG_AI_PROMPT
+resource "coder_script" "agentapi" {
+  agent_id     = coder_agent.main.id
+  run_on_start = true
+  script       = <<EOT
+    #!/usr/bin/env bash
+    ARG_AI_PROMPT=${data.coder_parameter.ai_prompt.value} \
+    /tmp/run_agentapi.sh
+  EOT
+  ...
+}
+
+# The coder_ai_task resource associates the task to the app.
+resource "coder_ai_task" "task" {
+  sidebar_app {
+    id = coder_app.ai_agent.id
+  }
+}
+```
+
+## Tasks format from 2.28 onwards
+
+In v2.28 and above, the following changes were made:
+
+- The explicitly named "AI Prompt" parameter is deprecated. The task prompt is now available in the `coder_ai_task` resource (provider version 2.12 and above) and `coder_task` data source (provider version 2.13 and above).
+- Modules no longer define the `coder_ai_task` resource. These must be defined explicitly in the template.
+- The `sidebar_app` field of the `coder_ai_task` resource is now deprecated. In its place, use `app_id`.
+
+Example (**not** a full template):
+
+```hcl
+terraform {
+  required_providers {
+    coder = {
+      source = "coder/coder
+      version = ">= 2.13.0
+    }
+  }
+}
+
+data "coder_workspace" "me" {}
+
+# The prompt is now available in the coder_task data source.
+data "coder_task" "me" {}
+
+resource "coder_agent" "main" { ... }
+
+# This coder_app is the interface to the Coder Task.
+# This is assumed to be a running instance of coder/agentapi (for instance, started via `coder_script`).
+resource "coder_app" "ai_agent" {
+  ...
+}
+
+# Assuming that the below script runs `coder/agentapi` with the prompt
+# defined in ARG_AI_PROMPT
+resource "coder_script" "agentapi" {
+  agent_id     = coder_agent.main.id
+  run_on_start = true
+  script       = <<EOT
+    #!/usr/bin/env bash
+    ARG_AI_PROMPT=${data.coder_task.me.prompt} \
+    /tmp/run_agentapi.sh
+  EOT
+  ...
+}
+
+# The coder_ai_task resource associates the task to the app.
+resource "coder_ai_task" "task" {
+  app_id = coder_app.ai_agent.id
+}
+```
diff --git a/docs/ai-coder/tasks.md b/docs/ai-coder/tasks.md
@@ -39,16 +39,22 @@ Try prompts such as:
 - "document the project structure"
 - "change the primary color theme to purple"
 
-To import the template and begin configuring it, follow the [documentation in the Coder Registry](https://registry.coder.com/templates/coder-labs/tasks-docker)
+To import the template and begin configuring it, import the example [Run Coder Tasks on Docker](https://github.com/coder/coder/tree/main/examples/templates/tasks-docker) template.
 
 ### Option 2&rpar; Create or Duplicate Your Own Template
 
-A template becomes a Task template if it defines a `coder_ai_task` resource and a `coder_parameter` named `"AI Prompt"`. Coder analyzes template files during template version import to determine if these requirements are met. Try adding this terraform block to an existing template where you'll add our Claude Code module. Note: the `coder_ai_task` resource is defined within the [Claude Code Module](https://registry.coder.com/modules/coder/claude-code?tab=readme), so it's not defined within this block.
+A template becomes a Task-capable template if it defines a `coder_ai_task` resource. Coder analyzes template files during template version import to determine if these requirements are met. Try adding this terraform block to an existing template where you'll add our Claude Code module.
+
+> [!NOTE] The `coder_ai_task` resource is not defined within the [Claude Code Module](https://registry.coder.com/modules/coder/claude-code?tab=readme). You need to define it yourself.
 
 ```hcl
-data "coder_parameter" "ai_prompt" {
-    name = "AI Prompt"
-    type = "string"
+terraform {
+  required_providers {
+    coder = {
+      source = "coder/coder"
+      version = ">= 2.13"
+    }
+  }
 }
 
 data "coder_parameter" "setup_script" {
@@ -61,12 +67,18 @@ data "coder_parameter" "setup_script" {
   default      = ""
 }
 
+data "coder_task" "me" {}
+
+resource "coder_ai_task" "task" {
+  app_id = module.claude-code.task_app_id
+}
+
 # The Claude Code module does the automatic task reporting
 # Other agent modules: https://registry.coder.com/modules?search=agent
 # Or use a custom agent:
 module "claude-code" {
   source   = "registry.coder.com/coder/claude-code/coder"
-  version  = "3.0.1"
+  version  = "4.0.0"
   agent_id = coder_agent.example.id
   workdir  = "/home/coder/project"
 
@@ -77,7 +89,7 @@ module "claude-code" {
   claude_code_version = "1.0.82" # Pin to a specific version
   agentapi_version    = "v0.6.1"
 
-  ai_prompt = data.coder_parameter.ai_prompt.value
+  ai_prompt = data.coder_task.me.prompt
   model     = "sonnet"
 
   # Optional: run your pre-flight script
@@ -105,16 +117,15 @@ variable "anthropic_api_key" {
 }
 ```
 
-> [!NOTE]
-> This definition is not final and may change while Tasks is in beta. After any changes, we guarantee backwards compatibility for one minor Coder version. After that, you may need to update your template to continue using it with Tasks.
-
 Because Tasks run unpredictable AI agents, often for background tasks, we recommend creating a separate template for Coder Tasks with limited permissions. You can always duplicate your existing template, then apply separate network policies/firewalls/permissions to the template. From there, follow the docs for one of our [built-in modules for agents](https://registry.coder.com/modules?search=tag%3Atasks) in order to add it to your template, configure your LLM provider.
 
 Alternatively, follow our guide for [custom agents](./custom-agents.md).
 
+> [!IMPORTANT] Upgrading from Coder v2.27 or earlier? See the [Tasks Migration Guide](./tasks-migration.md) for breaking changes in v2.28.0.
+
 ## Customizing the Task UI
 
-The Task UI displays all workspace apps declared in a Task template. You can customize the app shown in the sidebar using the `sidebar_app.id` field on the `coder_ai_task` resource.
+The Task UI displays all workspace apps declared in a Task template. You can customize the app shown in the sidebar using the `app_id` field on the `coder_ai_task` resource.
 
 If a workspace app has the special `"preview"` slug, a navbar will appear above it. This is intended for templates that let users preview a web app they’re working on.
 

diff --git a/docs/manifest.json b/docs/manifest.json
@@ -905,6 +905,12 @@
 							"path": "./ai-coder/custom-agents.md",
 							"state": ["beta"]
 						},
+						{
+							"title": "Tasks Migration Guide",
+							"description": "Changes to Coder Tasks made in v2.28",
+							"path": "./ai-coder/tasks-migration.md",
+							"state": ["beta"]
+						},
 						{
 							"title": "Security \u0026 Boundaries",
 							"description": "Learn about security and boundaries when running AI coding agents in Coder",

diff --git a/docs/tutorials/quickstart.md b/docs/tutorials/quickstart.md
@@ -239,7 +239,7 @@ advanced capabilities that Coder offers.
 ### Get Coder Tasks Running
 
 Coder Tasks is an interface that allows you to run and manage coding agents like
-Claude Code within a given Workspace. Tasks become available when the Template for a Workspace has the `coder_ai_task` resource and `coder_parameter` named `AI Prompt` defined in its source code.
+Claude Code within a given Workspace. Tasks become available when a Workspace Template has the `coder_ai_task` resource defined in its source code.
 In other words, any existing template can become a Task template by adding in that
 resource and parameter.