Skip to content

Commit b6935c3

Browse files
johnstcnbpmct
johnstcn
and
bpmct
authored
chore(docs/ai-coder): add migration guide for provider version 2.13.0 (#20426)
Closes coder/internal#1080 --------- Co-authored-by: Ben Potter <ben@coder.com>
1 parent e96ab0e commit b6935c3

File tree

5 files changed

+218
-34
lines changed

5 files changed

+218
-34
lines changed

‎docs/ai-coder/tasks-core-principles.md‎

Lines changed: 27 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -49,19 +49,16 @@ There are two approaches to turning a Template into a Task Template:
4949

5050
You can use a pre-existing agent module that [Coder maintains](https://registry.coder.com/modules). When using an agent module, you must define:
5151

52-
- `coder_parameter` named _ai_prompt_: Define the AI prompt input so users can define/specify what tasks need to run
52+
- `coder_ai_task` resource: links a `coder_app` to a Task.
5353
- **Agentic Module** that defines the agent you want to use, e.g. Claude Code, Codex CLI, Gemini CLI
5454

55-
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.
55+
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.
5656

57-
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.
57+
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.
5858

59-
```hcl
60-
data "coder_parameter" "ai_prompt" {
61-
name = "AI Prompt"
62-
type = "string"
63-
}
59+
> [!NOTE] This requires at least version 2.13.0 of the `coder/coder` Terraform provider.
6460
61+
```hcl
6562
data "coder_parameter" "setup_script" {
6663
name = "setup_script"
6764
display_name = "Setup Script"
@@ -72,12 +69,18 @@ data "coder_parameter" "setup_script" {
7269
default = ""
7370
}
7471
72+
data "coder_task" "me" {}
73+
74+
resource "coder_ai_task" "task" {
75+
app_id = module.claude-code.task_app_id
76+
}
77+
7578
# The Claude Code module does the automatic task reporting
7679
# Other agent modules: https://registry.coder.com/modules?search=agent
77-
# Or use a custom agent:
80+
# Or use a custom agent:
7881
module "claude-code" {
7982
source = "registry.coder.com/coder/claude-code/coder"
80-
version = "3.0.1"
83+
version = "4.0.0"
8184
agent_id = coder_agent.example.id
8285
workdir = "/home/coder/project"
8386
@@ -88,7 +91,7 @@ module "claude-code" {
8891
claude_code_version = "1.0.82" # Pin to a specific version
8992
agentapi_version = "v0.6.1"
9093
91-
ai_prompt = data.coder_parameter.ai_prompt.value
94+
ai_prompt = data.coder_task.me.prompt
9295
model = "sonnet"
9396
9497
# Optional: run your pre-flight script
@@ -118,30 +121,32 @@ variable "anthropic_api_key" {
118121

119122
Let's break down this snippet:
120123

121-
- 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)
122-
- 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
124+
- 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)
125+
- 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`
126+
- 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.
123127
- 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
124128

125129
#### Using a Custom Agent
126130

127131
Coder allows you to define a custom agent. When doing so, you must define:
128132

129-
- `coder_parameter` named _ai_prompt_: Define the AI prompt input so users can define/specify what tasks need to run
130-
- `coder_ai_task` which registers the task with the UI and allows the task to be visible
131-
- **AgentAPI binary** which provides runtime execution logistics for the task
133+
- 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.
134+
- A `coder_ai_task` resource which associates the `coder_app` related to the AI agent with the Task.
132135

133-
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.
136+
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.
134137

135138
Read more about [custom agents here](https://coder.com/docs/ai-coder/custom-agents).
136139

137140
#### Putting it all Together
138141

139142
Coder recommends using pre-existing agent modules when making a Task Template. Making a Task Template boils down to:
140143

141-
1. Identify the existing agent you want access to in our [Registry](https://registry.coder.com/modules)
142-
1. Add the agent's module to your existing template
143-
1. Define the module's required inputs
144-
1. Define the `coder_parameter`
144+
1. Identify the existing agent you want access to in our [Registry](https://registry.coder.com/modules).
145+
1. Add the agent's module to your existing template.
146+
1. Define the `coder_ai_task` resource and `coder_task` data source.
147+
1. Wire in the module's inputs and outputs:
148+
- Pass the prompt from the `coder_task` data source into the module.
149+
- Pass the module's `task_app_id` output into the `coder_ai_task` resource.
145150

146151
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.
147152

@@ -163,7 +168,7 @@ These design principles aren’t just technical guidelines; they're the lens thr
163168

164169
### Practical Considerations
165170

166-
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.
171+
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.
167172

168173
### Identity, Security, and Access
169174

‎docs/ai-coder/tasks-migration.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Migrating Task Templates for Coder version 2.28.0
2+
3+
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:
4+
5+
1. A Coder parameter specifically named `"AI Prompt"`,
6+
2. A `coder_workspace_app` that runs the `coder/agentapi` binary,
7+
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.
8+
9+
Note that 2 and 3 were generally handled by the `coder/agentapi` Terraform module.
10+
11+
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.
12+
13+
You can view an [example migration here](https://github.com/coder/coder/pull/20420). Alternatively, follow the steps below:
14+
15+
## Upgrade Steps
16+
17+
1. Update the Coder Terraform provider to at least version 2.13.0:
18+
19+
```diff
20+
terraform {
21+
required_providers {
22+
coder = {
23+
source = "coder/coder"
24+
- version = "x.y.z"
25+
+ version = ">= 2.13"
26+
}
27+
}
28+
}
29+
```
30+
31+
1. Define a `coder_ai_task` resource and `coder_task` data source in your template:
32+
33+
```diff
34+
+data "coder_task" "me" {}
35+
+resource "coder_ai_task" "task" {}
36+
```
37+
38+
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.
39+
40+
```diff
41+
module "claude-code" {
42+
source = "registry.coder.com/coder/claude-code/coder"
43+
- version = "4.0.0"
44+
+ version = "4.0.0"
45+
...
46+
- ai_prompt = data.coder_parameter.ai_prompt.value
47+
+ ai_prompt = data.coder_task.me.prompt
48+
}
49+
```
50+
51+
1. Add the `coder_ai_task` resource and set `app_id` to the `task_app_id` output of the Claude module.
52+
53+
> [!NOTE] Refer to the documentation for the specific module you are using for the exact name of the output.
54+
55+
```diff
56+
resource "coder_ai_task" "task" {
57+
+ app_id = module.claude-code.task_app_id
58+
}
59+
```
60+
61+
## Coder Tasks format pre-2.28
62+
63+
Below is a minimal illustrative example of a Coder Tasks template pre-2.28.0.
64+
**Note that this is NOT a full template.**
65+
66+
```hcl
67+
terraform {
68+
required_providers {
69+
coder = {
70+
source = "coder/coder
71+
}
72+
}
73+
}
74+
75+
data "coder_workspace" "me" {}
76+
77+
resource "coder_agent" "main" { ... }
78+
79+
# The prompt is passed in via the specifically named "AI Prompt" parameter.
80+
data "coder_parameter" "ai_prompt" {
81+
name = "AI Prompt"
82+
mutable = true
83+
}
84+
85+
# This coder_app is the interface to the Coder Task.
86+
# This is assumed to be a running instance of coder/agentapi
87+
resource "coder_app" "ai_agent" {
88+
...
89+
}
90+
91+
# Assuming that the below script runs `coder/agentapi` with the prompt
92+
# defined in ARG_AI_PROMPT
93+
resource "coder_script" "agentapi" {
94+
agent_id = coder_agent.main.id
95+
run_on_start = true
96+
script = <<EOT
97+
#!/usr/bin/env bash
98+
ARG_AI_PROMPT=${data.coder_parameter.ai_prompt.value} \
99+
/tmp/run_agentapi.sh
100+
EOT
101+
...
102+
}
103+
104+
# The coder_ai_task resource associates the task to the app.
105+
resource "coder_ai_task" "task" {
106+
sidebar_app {
107+
id = coder_app.ai_agent.id
108+
}
109+
}
110+
```
111+
112+
## Tasks format from 2.28 onwards
113+
114+
In v2.28 and above, the following changes were made:
115+
116+
- 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).
117+
- Modules no longer define the `coder_ai_task` resource. These must be defined explicitly in the template.
118+
- The `sidebar_app` field of the `coder_ai_task` resource is now deprecated. In its place, use `app_id`.
119+
120+
Example (**not** a full template):
121+
122+
```hcl
123+
terraform {
124+
required_providers {
125+
coder = {
126+
source = "coder/coder
127+
version = ">= 2.13.0
128+
}
129+
}
130+
}
131+
132+
data "coder_workspace" "me" {}
133+
134+
# The prompt is now available in the coder_task data source.
135+
data "coder_task" "me" {}
136+
137+
resource "coder_agent" "main" { ... }
138+
139+
# This coder_app is the interface to the Coder Task.
140+
# This is assumed to be a running instance of coder/agentapi (for instance, started via `coder_script`).
141+
resource "coder_app" "ai_agent" {
142+
...
143+
}
144+
145+
# Assuming that the below script runs `coder/agentapi` with the prompt
146+
# defined in ARG_AI_PROMPT
147+
resource "coder_script" "agentapi" {
148+
agent_id = coder_agent.main.id
149+
run_on_start = true
150+
script = <<EOT
151+
#!/usr/bin/env bash
152+
ARG_AI_PROMPT=${data.coder_task.me.prompt} \
153+
/tmp/run_agentapi.sh
154+
EOT
155+
...
156+
}
157+
158+
# The coder_ai_task resource associates the task to the app.
159+
resource "coder_ai_task" "task" {
160+
app_id = coder_app.ai_agent.id
161+
}
162+
```

‎docs/ai-coder/tasks.md‎

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -39,16 +39,22 @@ Try prompts such as:
3939
- "document the project structure"
4040
- "change the primary color theme to purple"
4141

42-
To import the template and begin configuring it, follow the [documentation in the Coder Registry](https://registry.coder.com/templates/coder-labs/tasks-docker)
42+
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.
4343

4444
### Option 2&rpar; Create or Duplicate Your Own Template
4545

46-
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.
46+
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.
47+
48+
> [!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.
4749
4850
```hcl
49-
data "coder_parameter" "ai_prompt" {
50-
name = "AI Prompt"
51-
type = "string"
51+
terraform {
52+
required_providers {
53+
coder = {
54+
source = "coder/coder"
55+
version = ">= 2.13"
56+
}
57+
}
5258
}
5359
5460
data "coder_parameter" "setup_script" {
@@ -61,12 +67,18 @@ data "coder_parameter" "setup_script" {
6167
default = ""
6268
}
6369
70+
data "coder_task" "me" {}
71+
72+
resource "coder_ai_task" "task" {
73+
app_id = module.claude-code.task_app_id
74+
}
75+
6476
# The Claude Code module does the automatic task reporting
6577
# Other agent modules: https://registry.coder.com/modules?search=agent
6678
# Or use a custom agent:
6779
module "claude-code" {
6880
source = "registry.coder.com/coder/claude-code/coder"
69-
version = "3.0.1"
81+
version = "4.0.0"
7082
agent_id = coder_agent.example.id
7183
workdir = "/home/coder/project"
7284
@@ -77,7 +89,7 @@ module "claude-code" {
7789
claude_code_version = "1.0.82" # Pin to a specific version
7890
agentapi_version = "v0.6.1"
7991
80-
ai_prompt = data.coder_parameter.ai_prompt.value
92+
ai_prompt = data.coder_task.me.prompt
8193
model = "sonnet"
8294
8395
# Optional: run your pre-flight script
@@ -105,16 +117,15 @@ variable "anthropic_api_key" {
105117
}
106118
```
107119

108-
> [!NOTE]
109-
> 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.
110-
111120
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.
112121

113122
Alternatively, follow our guide for [custom agents](./custom-agents.md).
114123

124+
> [!IMPORTANT] Upgrading from Coder v2.27 or earlier? See the [Tasks Migration Guide](./tasks-migration.md) for breaking changes in v2.28.0.
125+
115126
## Customizing the Task UI
116127

117-
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.
128+
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.
118129

119130
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.
120131

‎docs/manifest.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -905,6 +905,12 @@
905905
"path": "./ai-coder/custom-agents.md",
906906
"state": ["beta"]
907907
},
908+
{
909+
"title": "Tasks Migration Guide",
910+
"description": "Changes to Coder Tasks made in v2.28",
911+
"path": "./ai-coder/tasks-migration.md",
912+
"state": ["beta"]
913+
},
908914
{
909915
"title": "Security \u0026 Boundaries",
910916
"description": "Learn about security and boundaries when running AI coding agents in Coder",

‎docs/tutorials/quickstart.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -239,7 +239,7 @@ advanced capabilities that Coder offers.
239239
### Get Coder Tasks Running
240240

241241
Coder Tasks is an interface that allows you to run and manage coding agents like
242-
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.
242+
Claude Code within a given Workspace. Tasks become available when a Workspace Template has the `coder_ai_task` resource defined in its source code.
243243
In other words, any existing template can become a Task template by adding in that
244244
resource and parameter.
245245

0 commit comments

Comments
 (0)