docs: add Tasks to Chats API migration guide#24841
Merged
Merged
Conversation
Add a migration guide for customers moving from the Tasks API (/api/v2/tasks) to the Chats API (/api/experimental/chats) for Coder Agents. Covers endpoint mapping, architectural differences, step-by-step migration instructions, template recommendations, and GitHub Actions integration updates. 🤖 Generated with [Coder Agents](https://coder.com/docs/ai-coder/agents)
Walk through verifying each step of the Chats API integration: experiment flag, LLM provider, chat creation, WebSocket streaming, follow-ups, workspace provisioning, interrupt, and archive/restore. Includes a quick checklist for CI or manual validation. 🤖 Generated with [Coder Agents](https://coder.com/docs/ai-coder/agents)
Docs preview |
…tation Cross-checked against codersdk.ChatStatus, exp_chats.go, and in-flight PRs (#24432 removes the agents experiment flag, #24828 documents which chat statuses are actually set on main). - docs/manifest.json: fix tab indentation that broke the closing brace - migration guide: - flag the agents experiment requirement as transitional (going away in May Beta per #24432) - require organization_id in the create-chat curl example (it is required by the API; was missing) - rewrite status table: paused/completed enum values exist but no production path on main currently sets them; add requires_action - replace 'no CLI yet' wording with the actual coder exp agents TUI and the planned coder agents graduation - add a note that a coder/create-agent-chat-action GHA is in flight (CODAGT-127) - frame the testing section's experiment check as transitional - replace UUID placeholder that tripped lint/typos Linear: CODAGT-157 > Coder Agent generated this commit on @david-fraley's behalf.
david-fraley
changed the title
CI's lint/emdash check (scripts/check_emdash.sh) flags U+2014 in the diff. Restructure prose with periods/semicolons/parentheses and replace empty-cell em-dash placeholders with 'n/a' to satisfy the check. No semantic change. > Coder Agent generated this commit on @david-fraley's behalf.
david-fraley
changed the title
david-fraley
changed the title
Reframe the section so the deprecation drives the migration. Calls out the v2.36 cutoff and the Premium-only ESR fallback that PR #24831 adds to the Tasks page, instead of leaving the choice as 'if you are adopting Coder Agents'. Linear: CODAGT-157 Refs: #24831 \u003e Coder Agent generated this commit on @david-fraley's behalf.
The action exists at coder/create-agent-chat-action and is the supported migration path for create-task-action workflows. Rewrite the GHA section to point users at the action instead of an inline curl, with a note that new features are actively shipping. Linear: CODAGT-157 > Coder Agent generated this commit on @david-fraley's behalf.
Two regressions from 8c0a1b2 that fail markdownlint and would block CI: - MD009: trailing space after the new getting-started link - MD051: stale '#2-configure-an-llm-provider' fragment in the testing section now that the experiment step is removed and Configure an LLM provider is step 1 > Coder Agent generated this commit on @david-fraley's behalf.
Match the migration-steps section, which no longer enables the agents experiment. Renumber remaining test steps 2-8 to 1-7 and remove the matching checklist item. > Coder Agent generated this commit on @david-fraley's behalf.
The previous step relied on the agent picking the right template and auto-provisioning a workspace, which is hard to verify against. Replace with a UI flow that asks the user to create a workspace from the converted template, attach it to a chat from the composer, and confirm the chat drives that workspace. Update the matching checklist item. > Coder Agent generated this commit on @david-fraley's behalf.
Pre-creating a workspace from a known template via POST /workspaces and passing its workspace_id on chat creation gives users the template_version_id-style determinism they had with Tasks. Add it as a best-practice subsection right before the testing flow. > Coder Agent generated this commit on @david-fraley's behalf.
Drop the 'best practice' framing in favor of presenting the pre-created-workspace flow as one option for deterministic results. > Coder Agent generated this commit on @david-fraley's behalf.
'Option:' read like a config-UI label. Switch to 'Pre-creating a workspace for deterministic results', which matches the topic-noun style of nearby subsections (What to include in agent templates, What to remove from migrated task templates). > Coder Agent generated this commit on @david-fraley's behalf.
- Drop CODER_EXPERIMENTS=agents references; the flag was removed by #24432 - Keep 'coder exp agents' per @david-fraley's direction (the API is still experimental) even though #24432 also graduated the CLI to 'coder agents' - Repoint chats-api.md link to ../../reference/api/chats.md (deletion in #24830) - Flip manifest state to beta to match the rest of /agents/ post-#24826 - Clarify that 'waiting' is both the initial idle state and the post- completion idle state in the status mapping table
Collaborator
Author
|
Pushed updates addressing the accuracy-check findings:
|
mattvollmer
added a commit
that referenced
this pull request
May 4, 2026
…#24929) Updates `docs/ai-coder/index.md`, `docs/ai-coder/best-practices.md`, and `docs/ai-coder/ai-governance.md` to point readers at Coder Agents and the AI Governance Add-On instead of Coder Tasks and Agent Firewall (CODAGT-157). ## Changes - `docs/ai-coder/index.md`: - Rename `## Agents with Coder Tasks` to `## Coder Agents`. Drop the Devin / ChatGPT Codex name-drops and the Tasks pitch. New copy points at `./agents/index.md`, names the agent loop in the control plane, and notes that workspaces can be completely network isolated. Image swapped from `tasks-ui.png` to `agents-hero-image.png` (the hero shot added in #24915). - Replace the `## Secure Your Workflows with Agent Firewall` section with `## Govern AI activity with the AI Governance Add-On`. The new section opens with adoption-first framing (visibility, guardrails, cost) and links to `./ai-governance.md`, with bulleted callouts for AI Gateway, Agent Firewall, and the expanded Agent Workspace Build allowance the add-on bundles. - `docs/ai-coder/best-practices.md`: - In the use-case table, swap `[Tasks](./tasks.md)` to `[Coder Agents](./agents/index.md)` for the developer-led-investigation and prototyping rows, and swap the "Tasks API *(in development)*" cell to `[Coder Agents API](./agents/chats-api.md)` for the background-jobs row. Retitle the Security section link from "securing agents with Coder Tasks" to "securing AI agents" since `security.md` does not actually mention Tasks. Re-ran `markdown-table-formatter` to repad column widths. - In `## Provide Agents with Proper Context`, add a paragraph describing how context is provided in Coder Agents (admin-configured system prompts, centrally registered MCP servers, and skills shipped from repos or templates under `.agents/skills/`), with a transition line clarifying that the existing Memory and Tools subsections cover BYO-agent patterns. - `docs/ai-coder/ai-governance.md`: drop the "Additional Tasks Use (via Agent Workspace Builds)" bullet from the intro feature list and the "Expanding the use of Coder Tasks for AI-driven background work" bullet from the audience list. The `## How Coder Tasks usage is measured` section and the rest of the Tasks-related prose on this page are intentionally left for a follow-up PR. ## Notes for the reviewer - The `[Coder Agents API](./agents/chats-api.md)` link in `best-practices.md` will need to be retargeted if #24830 (which replaces `agents/chats-api.md` with auto-generated `reference/api/chats.md`) lands first. - This is the first slice of the Tasks-references audit. Remaining files (`tasks-core-principles.md`, `tasks-lifecycle.md`, `tasks-migration.md`, `cli.md`, `github-to-tasks.md`, `agent-compatibility.md`, the rest of `ai-governance.md`, `custom-agents.md`, `ai-gateway/clients/claude-code.md`, `manifest.json`, `reference/api/tasks.md`, the `task*` CLI references, the ESR upgrade guide, `feature-stages.md`, `workspace-scheduling.md`, `shared-workspaces.md`) will land in follow-up PRs against the same Linear ticket. Open PRs #24831, #24833, and #24841 cover separate slices and do not touch any file in this PR. - Validation: `markdownlint-cli2`, `markdown-table-formatter`, `scripts/check_emdash.sh`, and `make pre-commit-light` all pass. PR generated with Coder Agents.
Co-authored-by: Cian Johnston <cian@coder.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Linear: CODAGT-157 (Tasks → Chats migration guide for the May Beta).
New page at
docs/ai-coder/agents/tasks-to-chats-migration.mdplus amanifest.jsonnav entry.The guide maps each Tasks API endpoint, request shape, status, and lifecycle operation onto the experimental Chats API, with explicit before/after
curlexamples, a step-by-step migration plan, a how-to-test section, and a CLI/GHA migration table.Cross-checks against
mainand in-flight PRsReviewed against
codersdk/chats.go,coderd/exp_chats.go, andcoderd/coderd.goto confirm endpoint paths, request shapes, and status values match what the server actually accepts and emits. Also reconciled with these open PRs that touch the same surface:agentsexperiment flagCODER_EXPERIMENTS="agents"setup step disappears for May Betacoder agentsgraduationEarly AccessbecomesBetaacross the agents docsstateleft asearly accessto merge cleanly with currentmanifest.jsonand flip in #24826's passpaused/completedfrom thechats-api.mdstatus table because no production path onmainsets thempending/running/waiting/error/requires_actionare presented as live states;paused/completedare explicitly called out as enum-onlychats-api.mdwithdocs/reference/api/chats.mdchats-api.mdfor now; will be repointed in #24830's follow-up if it merges firstcoder/create-agent-chat-actionGHAcreate-task-actionparity in developmentcurlexample but adds a callout for the dedicated actionFixes applied during review
docs/manifest.jsonindentation was broken. The patch chunk had misaligned tabs that left]\t\t\t\t}on a single line. JSON parsed but rendered oddly. Re-indented to match the surrounding nav entries.organization_idin the create-chat example.POST /api/experimental/chatsrejects requests without it (organization_id is required.,coderd/exp_chats.go:616). Added to the example body and the "Key differences" list.pausedandcompletedas live Chats statuses. Per docs(docs/ai-coder/agents): correct chat statuses, watch events, auto-archive default, and add attach_file tool #24828 (and agrepagainstmain), neither is set by any production code path; they exist only incodersdk.ChatStatusfor future use. Replaced the row mappingpaused -> pausedwith a note explaining the workspace-pause vs. agent-interrupt difference, added a row forrequires_action, and clarified thatwaitingis the canonical "agent is done" state.agentsexperiment framed as required. Flagged as transitional in three places (note callout, Step 1, testing section, checklist) so readers on the May Beta release don't get confused by aCODER_EXPERIMENTSflag that no longer exists.coder exp agentsexists today (cli/exp_agents.go) and is graduating tocoder agentsper chore: remove agents experiment flag and mark feature as beta #24432. Replaced the "no CLI yet" wording with the actual command and the planned rename.coder/create-agent-chat-action(CODAGT-127) so readers know an inlinecurlis the v0 pattern.lint/typosfalse positive. The example"template_version_id": "0ba39c92-..."tripped thebatoby/berule. Replaced with<template-version-uuid>placeholder.lint/emdashfailures. CI'sscripts/check_emdash.shrejects U+2014/U+2013 in the diff. Restructured prose with periods, semicolons, and parentheses; replaced empty-cell em-dash placeholders in tables withn/a. No semantic change.Validation
pnpm exec markdownlint-cli2 docs/ai-coder/agents/tasks-to-chats-migration.mdreturns 0 errorspnpm exec markdown-table-formatter docs/ai-coder/agents/tasks-to-chats-migration.mdis stable (no diff after rerun)python3 -c "import json; json.load(open('docs/manifest.json'))"reports valid JSONmake pre-commit-light(via githook) passes all checksgrep -P "\xE2\x80\x94|\xE2\x80\x93" docs/ai-coder/agents/tasks-to-chats-migration.md docs/manifest.jsonreturns no matchescoderd/coderd.go(tasks routes, line 1948) andcoderd/exp_chats.goagainst the doc's endpoint mapping tableProof
Text-only docs change. Visible-string diffs are in the commits. The doc preview on
coder.comis linked from the PR comment (Docs preview) once CI rebuilds.Notes on what was intentionally not changed in this PR
state: ["early access"]inmanifest.jsonleft alone so this PR merges cleanly against docs: rename Early Access to Beta and remove early-access page #24826 (Beta rename), which flips every state in one pass../chats-api.mdlinks left in place pending docs: generate Chats API docs from swagger annotations #24830 (which retargets them to../../reference/api/chats.md).<!-- NEEDS REVIEW: ... -->and<!-- TODO: ... -->comments in the Template recommendations section are deliberately preserved as in-doc reviewer prompts. These will be removed once platform teams validate the recommendations.