Problem

The REST API reference page at /docs/reference/api/agents is confusing: by the name alone, a reader looking for the AI Coder Agents programmatic API would assume this is the right page. In fact, those endpoints are for the workspace agent daemon (the coder_agent Terraform resource / workspaceagent daemon). The actual AI Coder Agents API is documented at /docs/reference/api/chats.

Both pages compound the confusion by being rendered with a bare # Agents / # Chats heading and no descriptive intro. The sidebar entries are similarly ambiguous (Agents and Chats with no descriptions).

Root cause

The reference pages are generated by scripts/apidocgen/generate.sh (swag → widdershins → postprocess). The widdershins template (scripts/apidocgen/markdown-template/main.dot) already renders data.resource.description directly under each section heading:

<!-- APIDOCGEN: BEGIN SECTION -->
{{= data.tags.section }}# {{= r}}

{{? data.resource.description }}{{= data.resource.description}}{{?}}

…but the swag annotations in coderd/coderd.go never declared @tag.name / @tag.description for any tag, so the descriptions were always empty.

Changes

• coderd/coderd.go: add @tag.name Agents / @tag.description … and @tag.name Chats / @tag.description … annotations next to the existing @title / @version block.
• docs/manifest.json: rename the sidebar entry Agents → Workspace Agents and add description fields to both API sidebar entries (every other top-level section in the manifest has descriptions; the API children did not).
• Regenerate coderd/apidoc/swagger.json, coderd/apidoc/docs.go, docs/reference/api/agents.md, and docs/reference/api/chats.md via scripts/apidocgen/generate.sh + pnpm exec markdownlint-cli2 --fix + pnpm exec markdown-table-formatter + scripts/biome_format.sh (matching the Makefile's coderd/apidoc/.gen pipeline).

Resulting diff is intentionally minimal — 6 files, 35 insertions / 3 deletions.

After this PR

The Agents page will render:

Agents

Workspace agent endpoints. These power the workspace agent daemon defined by the coder_agent Terraform resource (sometimes called the workspace daemon). This API is NOT the AI Coder Agents API. For programmatic access to AI Coder Agents (formerly Tasks), see the Chats API.

The Chats page will render:

Chats

Programmatic API for Coder AI Agents (the user-facing "Coder Agents" / "Chats" product). Experimental. Use these endpoints to create, list, and manage AI coding agent sessions. For background and migration from the Tasks API, see the AI Coder docs.

And the sidebar entry for the workspace-agent endpoints becomes Workspace Agents instead of Agents.

Out of scope (potential follow-ups)

• docs/reference/api/chat.md is a 7-byte stub — likely dead. Could be deleted in a follow-up.
• Larger rename of the Agents Swagger tag (and/or the coder_agent Terraform resource) to something like Workspace Agents / workspace_daemon would more thoroughly fix the naming collision, but that's a much bigger change.

Created on behalf of @mattvollmer.