mirror of
https://github.com/coder/coder.git
synced 2026-09-21 20:51:01 +08:00
8b970e7ff3
## Problem The REST API reference page at [`/docs/reference/api/agents`](https://coder.com/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`](https://coder.com/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. --------- Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com> Co-authored-by: Matt Vollmer <matthewjvollmer@outlook.com> Co-authored-by: Atif Ali <atif@coder.com>