### Configure an LLM provider [#configure-an-llm-provider]
With Tasks, LLM credentials are injected into the workspace as environment variables (e.g. `ANTHROPIC_API_KEY`).
With Coder Agents, credentials are configured once in the control plane:
1. Navigate to **Admin settings** > **AI** and select **Providers**.
2. Add or update a provider with its credentials and upstream endpoint, then save it.
3. Navigate to **Admin settings** > **AI** > **Models**.
4. Select the correct organization.
5. Add at least one model, and set it as the default.
You no longer pass API keys in template variables or workspace environment.
See [https://coder.com/docs/ai-coder/agents/getting-started](https://coder.com/docs/ai-coder/agents/getting-started) for more information.
### Update task creation calls [#update-task-creation-calls]
**Tasks API**.
You specify the user, template version, and a prompt string:
```sh
# Tasks API: create a task
curl -X POST https://coder.example.com/api/v2/tasks/me \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"template_version_id": "",
"input": "Fix the failing tests in the auth service"
}'
```
**Chats API**.
You send structured content parts.
No template or user path segment is required:
```sh
# Chats API: create a chat
curl -X POST https://coder.example.com/api/v2/chats \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"organization_id": "",
"content": [
{"type": "text", "text": "Fix the failing tests in the auth service"}
]
}'
```
Key differences:
* The `{user}` path parameter is removed.
The authenticated user is inferred from the session token.
* `organization_id` is required in the request body.
The caller must be a member of that organization.
* The prompt is now an array of `ChatInputPart` objects (supporting `text`, `file`, and `file-reference` types) instead of a plain string.
* `template_version_id` and `template_version_preset_id` are removed.
The agent selects a template automatically based on the prompt and available template descriptions.
To pin to a specific workspace, pass `workspace_id` instead.
* Optionally pass `model_config_id` to override the default model, or `mcp_server_ids` to attach MCP servers.
* Optionally pass `title` to set the chat's title.
A title you set is kept; automatic title generation runs only when `title` is omitted.
### Update follow-up message calls [#update-follow-up-message-calls]
**Tasks API**.
Follow-ups use the send endpoint with a plain string:
```sh
# Tasks API: send input
curl -X POST https://coder.example.com/api/v2/tasks/me/my-task/send \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"input": "Now also update the integration tests"}'
```
**Chats API**.
Follow-ups use the messages endpoint with content parts:
```sh
# Chats API: send a message
curl -X POST \
https://coder.example.com/api/v2/chats/$CHAT_ID/messages \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": [
{"type": "text", "text": "Now also update the integration tests"}
]
}'
```
The Chats API supports message queuing.
If the agent is busy, the message is queued automatically and delivered when the agent finishes its current step.
The response includes a `queued` field indicating whether the message was delivered immediately or queued.
### Switch from log polling to WebSocket streaming [#switch-from-log-polling-to-websocket-streaming]
**Tasks API**.
You poll for logs:
```sh
# Tasks API: get logs
curl https://coder.example.com/api/v2/tasks/me/my-task/logs \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN"
```
**Chats API**.
You open a one-way WebSocket connection:
```txt
GET wss://coder.example.com/api/v2/chats/{chat}/stream
```
The WebSocket sends JSON envelopes with a `type` field (`"ping"`, `"data"`, or `"error"`).
Data envelopes contain batches of events:
| Event type | Description |
| -------------- | ------------------------------------------------------- |
| `message_part` | A chunk of the agent's response (text, tool call, etc.) |
| `message` | A complete message has been persisted |
| `status` | The chat status changed (e.g. `running` → `waiting`) |
| `error` | An error occurred during processing |
| `retry` | The control plane is retrying a failed LLM call |
| `queue_update` | The queued message list changed |
Use `after_id` as a query parameter when reconnecting to skip messages the client already has.
### Update status handling [#update-status-handling]
Task and chat statuses use different values.
The Chats API status set is defined in `codersdk.ChatStatus`:
| Tasks API status | Chats API status | Notes |
| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| `pending` | `running` | Chats have no separate queued state; a chat that hasn't been picked up yet reports `running`. |
| `running` | `running` | Agent is actively working. |
| `complete` | `waiting` | Idle. Newly created, finished successfully, or interrupted. This is the default idle state. |
| `paused` | n/a | The Tasks API pause stops the workspace; the Chats API equivalent is `interrupt` plus separate workspace lifecycle. |
| `failed` | `error` | Agent encountered an error. |
| n/a | `requires_action` | Agent invoked a client-provided tool and is waiting for the result before continuing. |
| n/a | `interrupting` | An interrupt was requested and the agent is winding down the current run. |
The Chats API uses `waiting` as the default idle state (not `complete`).
A chat enters `waiting` when it is first created (before any message is queued) and again whenever a run finishes or is interrupted, so treat `waiting` as "the agent is not currently working" rather than only "the agent just finished."
### Replace delete with archive [#replace-delete-with-archive]
The Tasks API uses `DELETE` to remove a task.
The Chats API uses archiving:
```diff
- curl -X DELETE https://coder.example.com/api/v2/tasks/me/my-task \
- -H "Coder-Session-Token: $CODER_SESSION_TOKEN"
+ curl -X PATCH https://coder.example.com/api/v2/chats/$CHAT_ID \
+ -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"archived": true}'
```
Archived chats can be restored by setting `archived` to `false`.
### Replace pause/resume with interrupt and messaging [#replace-pauseresume-with-interrupt-and-messaging]
**Tasks API**.
Pause and resume stop and start the workspace:
```sh
# Tasks API
curl -X POST \
https://coder.example.com/api/v2/tasks/me/my-task/pause \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN"
curl -X POST \
https://coder.example.com/api/v2/tasks/me/my-task/resume \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN"
```
**Chats API**.
Interrupt stops the current agent loop.
Sending a new message resumes processing:
```sh
# Chats API: interrupt
curl -X POST \
https://coder.example.com/api/v2/chats/$CHAT_ID/interrupt \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN"
# Chats API: resume by sending a new message
curl -X POST \
https://coder.example.com/api/v2/chats/$CHAT_ID/messages \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": [
{"type": "text", "text": "Continue where you left off"}
]
}'
```
In the Tasks API, pausing stops the workspace and frees compute.
In the Chats API, interrupt stops the agent loop in the control plane; the workspace may remain running.
The workspace lifecycle is managed independently.
### Update GitHub Actions integrations [#update-github-actions-integrations]
If you use the [Create Task Action](https://github.com/coder/create-task-action) GitHub Action, replace it with the dedicated [`coder/create-agent-chat-action`](https://github.com/coder/create-agent-chat-action).
It handles the API call, the GitHub user lookup, and the optional issue comment, so most existing workflows can swap one `uses:` line and rename a few inputs.
We are actively shipping new features for `create-agent-chat-action`, so pin to a major version (for example `@v0`) and watch the [releases](https://github.com/coder/create-agent-chat-action/releases) for updates.
```diff
# .github/workflows/triage-bug.yaml
jobs:
coder-create-task:
runs-on: ubuntu-latest
if: github.event.label.name == 'coder'
steps:
- - name: Coder Create Task
- uses: coder/create-task-action@v0
- with:
- coder-url: ${{ secrets.CODER_URL }}
- coder-token: ${{ secrets.CODER_TOKEN }}
- coder-organization: "default"
- coder-template-name: "my-template"
- coder-task-name-prefix: "gh-task"
- coder-task-prompt: >-
- Use the gh CLI to read
- ${{ github.event.issue.html_url }},
- fix the issue, and create a PR.
- github-user-id: ${{ github.event.sender.id }}
- github-issue-url: ${{ github.event.issue.html_url }}
- github-token: ${{ github.token }}
- comment-on-issue: true
+ - name: Coder Create Agent Chat
+ uses: coder/create-agent-chat-action@v0
+ with:
+ coder-url: ${{ secrets.CODER_URL }}
+ coder-token: ${{ secrets.CODER_TOKEN }}
+ chat-prompt: >-
+ Use the gh CLI to read
+ ${{ github.event.issue.html_url }},
+ fix the issue, and create a PR.
+ github-url: ${{ github.event.issue.html_url }}
+ github-token: ${{ github.token }}
+ comment-on-issue: true
```
Key differences from the Tasks GHA:
* No `coder-template-name` or `coder-task-name-prefix`.
The agent auto-provisions a workspace; pass `workspace-id` if you want to pin to an existing workspace instead.
* The prompt input is renamed from `coder-task-prompt` to `chat-prompt`.
* LLM credentials are no longer passed through the template.
They are configured in the Coder control plane.
* No user mapping: the Tasks GHA's `github-user-id` input has no equivalent, because the chat is always owned by the user the `coder-token` belongs to and the Chats API has no owner override.
See the [action README](https://github.com/coder/create-agent-chat-action#inputs) for the full input and output reference, including the `existing-chat-id` input for sending follow-up messages on a previous chat.
## Template recommendations [#template-recommendations]