docs: move AI-agent docs out of tutorials and into a top-level section (#17231)

EdwardAngert · web-flow · commit ed20bab3e0dd · 2025-04-10T14:21:29.000-04:00
redirects in: https://github.com/coder/coder.com/pull/873 [preview](https://coder.com/docs/@move-ai-agents-up-1/coder-ai) - [x] icon - [x] shorten ~Modify or truncate the current~ title ~to reduce its length for improved readability, conciseness, or formatting consistency.~ - [x] Best practices & adding tools via MCP - edit title, desc, headings --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
diff --git a/docs/coder-ai/README.md b/docs/coder-ai/README.md
@@ -1,8 +1,9 @@
-# Run AI Agents in Coder (Early Access)
+# Use AI Coding Agents in Coder Workspaces
 
 > [!NOTE]
 >
-> This functionality is in early access and still evolving.
+> This functionality is in early access and is evolving rapidly.
+>
 > For now, we recommend testing it in a demo or staging environment,
 > rather than deploying to production.
 >
@@ -14,19 +15,19 @@ AI Coding Agents such as [Claude Code](https://docs.anthropic.com/en/docs/agents
 - Protyping web applications or landing pages
 - Researching / onboarding to a codebase
 - Assisting with lightweight refactors
-- Writing tests and documentation
+- Writing tests and draft documentation
 - Small, well-defined chores
 
 With Coder, you can self-host AI agents in isolated development environments with proper context and tooling around your existing developer workflows. Whether you are a regulated enterprise or an individual developer, running AI agents at scale with Coder is much more productive and secure than running them locally.
 
-![AI Agents in Coder](../../images/guides//ai-agents/landing.png)
+![AI Agents in Coder](../images/guides/ai-agents/landing.png)
 
 ## Prerequisites
 
 Coder is free and open source for developers, with a [premium plan](https://coder.com/pricing) for enterprises. You can self-host a Coder deployment in your own cloud provider.
 
-- A [Coder deployment](../../install/) with v2.21.0 or later
-- A Coder [template](../../admin/templates/) for your project(s).
+- A [Coder deployment](../install/index.md) with v2.21.0 or later
+- A Coder [template](../admin/templates/index.md) for your project(s).
 - Access to at least one ML model (e.g. Anthropic Claude, Google Gemini, OpenAI)
   - Cloud Model Providers (AWS Bedrock, GCP Vertex AI, Azure OpenAI) are supported with some agents
   - Self-hosted models (e.g. llama3) and AI proxies (OpenRouter) are supported with some agents
diff --git a/docs/coder-ai/agents.md b/docs/coder-ai/agents.md
@@ -2,9 +2,10 @@
 
 > [!NOTE]
 >
-> This page is not exhaustive and the landscape is evolving rapidly. Please
-> [open an issue](https://github.com/coder/coder/issues/new) or submit a pull
-> request if you'd like to see your favorite agent added or updated.
+> This page is not exhaustive and the landscape is evolving rapidly.
+>
+> Please [open an issue](https://github.com/coder/coder/issues/new) or submit a
+> pull request if you'd like to see your favorite agent added or updated.
 
 There are several types of coding agents emerging:
 
diff --git a/docs/coder-ai/best-practices.md b/docs/coder-ai/best-practices.md
@@ -1,8 +1,9 @@
-# Best Practices & Adding Tools via MCP
+# Model Context Protocols (MCP) and adding AI tools
 
 > [!NOTE]
 >
-> This functionality is in early access and still evolving.
+> This functionality is in early access and is evolving rapidly.
+>
 > For now, we recommend testing it in a demo or staging environment,
 > rather than deploying to production.
 >
@@ -21,18 +22,20 @@ for development. With AI Agents, this is no exception.
 
 ## Best Practices
 
-- Since agents are still early, it is best to use the most capable ML models you
-  have access to in order to evaluate their performance.
+- Use the most capable ML models you have access to in order to evaluate Agent
+  performance.
 - Set a system prompt with the `AI_SYSTEM_PROMPT` environment in your template
 - Within your repositories, write a `.cursorrules`, `CLAUDE.md` or similar file
   to guide the agent's behavior.
 - To read issue descriptions or pull request comments, install the proper CLI
   (e.g. `gh`) in your image/template.
 - Ensure your [template](./create-template.md) is truly pre-configured for
   development without manual intervention (e.g. repos are cloned, dependencies
-  are built, secrets are added/mocked, etc.)
-  > Note: [External authentication](../../admin/external-auth.md) can be helpful
+  are built, secrets are added/mocked, etc.).
+
+  > Note: [External authentication](../admin/external-auth.md) can be helpful
   > to authenticate with third-party services such as GitHub or JFrog.
+
 - Give your agent the proper tools via MCP to interact with your codebase and
   related services.
 - Read our recommendations on [securing agents](./securing.md) to avoid
diff --git a/docs/coder-ai/coder-dashboard.md b/docs/coder-ai/coder-dashboard.md
@@ -1,6 +1,7 @@
 > [!NOTE]
 >
-> This functionality is in early access and still evolving.
+> This functionality is in early access and is evolving rapidly.
+>
 > For now, we recommend testing it in a demo or staging environment,
 > rather than deploying to production.
 >
@@ -17,9 +18,9 @@
 Once you have an agent running and reporting activity to Coder, you can view
 status and switch between workspaces from the Coder dashboard.
 
-![Coder Dashboard](../../images/guides/ai-agents/workspaces-list.png)
+![Coder Dashboard](../images/guides/ai-agents/workspaces-list.png)
 
-![Workspace Details](../../images/guides/ai-agents/workspace-details.png)
+![Workspace Details](../images/guides/ai-agents/workspace-details.png)
 
 ## Next Steps
 
diff --git a/docs/coder-ai/create-template.md b/docs/coder-ai/create-template.md
@@ -2,7 +2,8 @@
 
 > [!NOTE]
 >
-> This functionality is in early access and still evolving.
+> This functionality is in early access and is evolving rapidly.
+>
 > For now, we recommend testing it in a demo or staging environment,
 > rather than deploying to production.
 >
@@ -27,7 +28,7 @@ template that has all of the tools and dependencies installed.
 
 This can be done in the Coder UI:
 
-![Duplicate template](../../images/guides/ai-agents/duplicate.png)
+![Duplicate template](../images/guides/ai-agents/duplicate.png)
 
 ## 2. Add a module for supported agents
 
@@ -48,7 +49,7 @@ report status back to the Coder control plane.
 
 The Coder dashboard should now show tasks being reported by the agent.
 
-![AI Agents in Coder](../../images/guides//ai-agents/landing.png)
+![AI Agents in Coder](../images/guides/ai-agents/landing.png)
 
 ## Next Steps
 
diff --git a/docs/coder-ai/custom-agents.md b/docs/coder-ai/custom-agents.md
@@ -2,7 +2,8 @@
 
 > [!NOTE]
 >
-> This functionality is in early access and still evolving.
+> This functionality is in early access and is evolving rapidly.
+>
 > For now, we recommend testing it in a demo or staging environment,
 > rather than deploying to production.
 >
diff --git a/docs/coder-ai/headless.md b/docs/coder-ai/headless.md
@@ -1,6 +1,7 @@
 > [!NOTE]
 >
-> This functionality is in early access and still evolving.
+> This functionality is in early access and is evolving rapidly.
+>
 > For now, we recommend testing it in a demo or staging environment,
 > rather than deploying to production.
 >
@@ -44,12 +45,12 @@ coder exp mcp configure cursor # Configure Cursor to interact with Coder
 ## Coder CLI
 
 Workspaces can be created, started, and stopped via the Coder CLI. See the
-[CLI docs](../../reference/cli/) for more information.
+[CLI docs](../reference/cli/index.md) for more information.
 
 ## REST API
 
 The Coder REST API can be used to manage workspaces and agents. See the
-[API docs](../../reference/api/) for more information.
+[API docs](../reference/api/index.md) for more information.
 
 ## Next Steps
 
diff --git a/docs/coder-ai/ide-integration.md b/docs/coder-ai/ide-integration.md
@@ -1,6 +1,7 @@
 > [!NOTE]
 >
-> This functionality is in early access and still evolving.
+> This functionality is in early access and is evolving rapidly.
+>
 > For now, we recommend testing it in a demo or staging environment,
 > rather than deploying to production.
 >
@@ -21,7 +22,7 @@ Once you have an agent running and reporting activity to Coder, you can view the
 status and switch between workspaces from the IDE. This can be very helpful for
 reviewing code, working along with the agent, and more.
 
-![IDE Integration](../../images/guides/ai-agents/ide-integration.png)
+![IDE Integration](../images/guides/ai-agents/ide-integration.png)
 
 ## Next Steps
 
diff --git a/docs/coder-ai/issue-tracker.md b/docs/coder-ai/issue-tracker.md
@@ -2,7 +2,8 @@
 
 > [!NOTE]
 >
-> This functionality is in early access and still evolving.
+> This functionality is in early access and is evolving rapidly.
+>
 > For now, we recommend testing it in a demo or staging environment,
 > rather than deploying to production.
 >
@@ -28,7 +29,7 @@ The [start-workspace](https://github.com/coder/start-workspace-action) GitHub
 action will create a Coder workspace based on a specific phrase in a comment
 (e.g. `@coder`).
 
-![GitHub Issue](../../images/guides/ai-agents/github-action.png)
+![GitHub Issue](../images/guides/ai-agents/github-action.png)
 
 When properly configured with an [AI template](./create-template.md), the agent
 will begin working on the issue.
@@ -39,15 +40,15 @@ We're working on adding support for an agent automatically creating pull
 requests and responding to your comments. Check back soon or
 [join our Discord](https://discord.gg/coder) to stay updated.
 
-![GitHub Pull Request](../../images/guides/ai-agents/github-pr.png)
+![GitHub Pull Request](../images/guides/ai-agents/github-pr.png)
 
 ## Integrating with Other Issue Trackers
 
 While support for other issue trackers is under consideration, you can can use
-the [REST API](../../reference/api/) or [CLI](../../reference/cli/) to integrate
+the [REST API](../reference/api/index.md) or [CLI](../reference/cli/index.md) to integrate
 with other issue trackers or CI pipelines.
 
-In addition, an [Open in Coder](../../admin/templates/open-in-coder.md) flow can
+In addition, an [Open in Coder](../admin/templates/open-in-coder.md) flow can
 be used to generate a URL and/or markdown button in your issue tracker to
 automatically create a workspace with specific parameters.
 
diff --git a/docs/coder-ai/securing.md b/docs/coder-ai/securing.md
@@ -1,6 +1,7 @@
 > [!NOTE]
 >
-> This functionality is in early access and still evolving.
+> This functionality is in early access and is evolving rapidly.
+>
 > For now, we recommend testing it in a demo or staging environment,
 > rather than deploying to production.
 >
diff --git a/docs/images/icons/wand.svg b/docs/images/icons/wand.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" fill="none" stroke="#fff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.25" class="lucide lucide-wand-icon lucide-wand" viewBox="0 0 24 24">
+  <path d="M15 4V2M15 16v-2M8 9h2M20 9h2M17.8 11.8 19 13M15 9h.01M17.8 6.2 19 5M3 21l9-9M12.2 6.2 11 5"/>
+</svg>
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -667,6 +667,68 @@
 				}
 			]
 		},
+		{
+			"title": "Run AI Coding Agents in Coder",
+			"description": "Learn how to run and integrate AI coding agents like GPT-Code, OpenDevin, or SWE-Agent in Coder workspaces to boost developer productivity.",
+			"path": "./coder-ai/README.md",
+			"icon_path": "./images/icons/wand.svg",
+			"state": ["early access"],
+			"children": [
+				{
+					"title": "Learn about coding agents",
+					"description": "Learn about the different AI agents and their tradeoffs",
+					"path": "./coder-ai/agents.md"
+				},
+				{
+					"title": "Create a Coder template for agents",
+					"description": "Create a purpose-built template for your AI agents",
+					"path": "./coder-ai/create-template.md",
+					"state": ["early access"]
+				},
+				{
+					"title": "Integrate with your issue tracker",
+					"description": "Assign tickets to AI agents and interact via code reviews",
+					"path": "./coder-ai/issue-tracker.md",
+					"state": ["early access"]
+				},
+				{
+					"title": "Model Context Protocols (MCP) and adding AI tools",
+					"description": "Improve results by adding tools to your AI agents",
+					"path": "./coder-ai/best-practices.md",
+					"state": ["early access"]
+				},
+				{
+					"title": "Supervise agents via Coder UI",
+					"description": "Interact with agents via the Coder UI",
+					"path": "./coder-ai/coder-dashboard.md",
+					"state": ["early access"]
+				},
+				{
+					"title": "Supervise agents via the IDE",
+					"description": "Interact with agents via VS Code or Cursor",
+					"path": "./coder-ai/ide-integration.md",
+					"state": ["early access"]
+				},
+				{
+					"title": "Programmatically manage agents",
+					"description": "Manage agents via MCP, the Coder CLI, and/or REST API",
+					"path": "./coder-ai/headless.md",
+					"state": ["early access"]
+				},
+				{
+					"title": "Securing agents in Coder",
+					"description": "Learn how to secure agents with boundaries",
+					"path": "./coder-ai/securing.md",
+					"state": ["early access"]
+				},
+				{
+					"title": "Custom agents",
+					"description": "Learn how to use custom agents with Coder",
+					"path": "./coder-ai/custom-agents.md",
+					"state": ["early access"]
+				}
+			]
+		},
 		{
 			"title": "Contributing",
 			"description": "Learn how to contribute to Coder",
@@ -710,67 +772,6 @@
 					"description": "Learn how to install and run Coder quickly",
 					"path": "./tutorials/quickstart.md"
 				},
-				{
-					"title": "Run AI Coding Agents with Coder",
-					"description": "Learn how to run and secure agents in Coder",
-					"path": "./tutorials/ai-agents/README.md",
-					"state": ["early access"],
-					"children": [
-						{
-							"title": "Learn about coding agents",
-							"description": "Learn about the different AI agents and their tradeoffs",
-							"path": "./tutorials/ai-agents/agents.md"
-						},
-						{
-							"title": "Create a Coder template for agents",
-							"description": "Create a purpose-built template for your AI agents",
-							"path": "./tutorials/ai-agents/create-template.md",
-							"state": ["early access"]
-						},
-						{
-							"title": "Integrate with your issue tracker",
-							"description": "Assign tickets to AI agents and interact via code reviews",
-							"path": "./tutorials/ai-agents/issue-tracker.md",
-							"state": ["early access"]
-						},
-						{
-							"title": "Best practices \u0026 adding tools via MCP",
-							"description": "Improve results by adding tools to your agents",
-							"path": "./tutorials/ai-agents/best-practices.md",
-							"state": ["early access"]
-						},
-						{
-							"title": "Supervise agents via Coder UI",
-							"description": "Interact with agents via the Coder UI",
-							"path": "./tutorials/ai-agents/coder-dashboard.md",
-							"state": ["early access"]
-						},
-						{
-							"title": "Supervise agents via the IDE",
-							"description": "Interact with agents via VS Code or Cursor",
-							"path": "./tutorials/ai-agents/ide-integration.md",
-							"state": ["early access"]
-						},
-						{
-							"title": "Programmatically manage agents",
-							"description": "Manage agents via MCP, the Coder CLI, and/or REST API",
-							"path": "./tutorials/ai-agents/headless.md",
-							"state": ["early access"]
-						},
-						{
-							"title": "Securing agents in Coder",
-							"description": "Learn how to secure agents with boundaries",
-							"path": "./tutorials/ai-agents/securing.md",
-							"state": ["early access"]
-						},
-						{
-							"title": "Custom agents",
-							"description": "Learn how to use custom agents with Coder",
-							"path": "./tutorials/ai-agents/custom-agents.md",
-							"state": ["early access"]
-						}
-					]
-				},
 				{
 					"title": "Write a Template from Scratch",
 					"description": "Learn how to author Coder templates",

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,8 @@`
`2`	`2`
`3`	`3`	`> [!NOTE]`
`4`	`4`	`>`
`5`		`-> This functionality is in early access and still evolving.`
	`5`	`+> This functionality is in early access and is evolving rapidly.`
	`6`	`+>`
`6`	`7`	`> For now, we recommend testing it in a demo or staging environment,`
`7`	`8`	`> rather than deploying to production.`
`8`	`9`	`>`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`> [!NOTE]`
`2`	`2`	`>`
`3`		`-> This functionality is in early access and still evolving.`
	`3`	`+> This functionality is in early access and is evolving rapidly.`
	`4`	`+>`
`4`	`5`	`> For now, we recommend testing it in a demo or staging environment,`
`5`	`6`	`> rather than deploying to production.`
`6`	`7`	`>`
`@@ -21,7 +22,7 @@ Once you have an agent running and reporting activity to Coder, you can view the`
`21`	`22`	`status and switch between workspaces from the IDE. This can be very helpful for`
`22`	`23`	`reviewing code, working along with the agent, and more.`
`23`	`24`
`24`		`-![IDE Integration](../../images/guides/ai-agents/ide-integration.png)`
	`25`	`+![IDE Integration](../images/guides/ai-agents/ide-integration.png)`
`25`	`26`
`26`	`27`	`## Next Steps`
`27`	`28`