chat.agent — advanced & operational
The full, version-pinned reference ships inside your installed @trigger.dev/sdk. Read it before writing code — it always matches the SDK version in this project, so it never drifts:
- Skill:
node_modules/@trigger.dev/sdk/skills/trigger-chat-agent-advanced/SKILL.md — Sessions primitive, custom transports/wire protocol, sub-agents, HITL, steering, actions, background injection, fast starts, resilience (compaction/recovery/OOM/large payloads), chat.local, testing, upgrades.
- Docs: the full, version-pinned docs ship bundled at
node_modules/@trigger.dev/sdk/docs/ai-chat/ (including patterns/ for HITL, sub-agents, sessions); the skill above lists the exact pages it draws from in its sources: frontmatter. Grep for an API, e.g. grep -rl "mockChatAgent" node_modules/@trigger.dev/sdk/docs/.
If those paths don't exist, @trigger.dev/sdk isn't installed yet — install it first. In a non-hoisted layout, resolve the package with node -p "require.resolve('@trigger.dev/sdk/package.json')" and read skills/ + docs/ beside it.
Common mistakes
CRITICAL: sending a follow-up by re-POSTing POST /api/v1/sessions.
// Wrong - a cached re-POST silently drops basePayload.message; basePayload is trigger config, not a channel
await fetch("/api/v1/sessions", { method: "POST", body: JSON.stringify({ ...createBody }) });
// Correct - append to the session's input channel
await fetch(`/realtime/v1/sessions/${id}/in/append`, { method: "POST", body: JSON.stringify({ kind: "message", payload }) });
Using the wrong token for .in / .out. Use publicAccessToken from the create response
body (session-scoped). The x-trigger-jwt response header is run-scoped and cannot subscribe.
Initializing chat.local in onChatStart. It is skipped on continuation runs, so run()
crashes with chat.local can only be modified after initialization. Init in onBoot.
chat.defer for the message-history write. A mid-stream refresh would read []. await that
write inline before the model streams; reserve chat.defer for analytics, audit, cache warming.
Giving the HITL tool an execute. streamText calls it immediately. Leave it execute-less;
the frontend supplies the answer via addToolOutput + sendAutomaticallyWhen.
Declaring sub-agent / heavy tools only on streamText. Also declare them on
chat.agent({ tools }) (or pass to convertToModelMessages(uiMessages, { tools }) in a custom
agent) so toModelOutput re-applies on every turn.
Importing heavy-execute tools into the Head Start route module. This is a build-time import
chain problem; runtime strip helpers do not fix it. Keep schemas in an ai + zod-only module.
Returning a megabyte tool output on the stream. One tool-output-available record over ~1 MiB
throws ChatChunkTooLargeError. Persist to your store, write the row first, then emit only an id.
Setting X-Peek-Settled: 1 on the active-send path. It races the new turn's first chunk and
closes the stream early. Use it only on reconnect-on-reload paths.
Note on docs vocabulary: agent-side examples in some docs still use the legacy
trigger:turn-complete chunk type. That is the agent-emit vocabulary. A custom reader must
filter on the trigger-control header, not on chunk.type.
MCP-driven agent chats (list_agents, start_agent_chat, send_agent_message,
close_agent_chat) are MCP server tools used from Claude Code / Cursor, not importable SDK
functions. See /mcp-tools#agent-chat-tools.
References
Sibling skills: trigger-authoring-chat-agent (the everyday chat.agent({...}) happy path), trigger-authoring-tasks and trigger-realtime-and-frontend (task + frontend foundations).
1---2name: trigger-chat-agent-advanced3description: Advanced and operational chat.agent capabilities for Trigger.dev, loaded on demand. Load this when working on the raw Sessions primitive (sessions / SessionHandle), a custom chat transport or the realtime wire protocol, durable sub-agents (AgentChat, chat.stream.writer), human-in-the-loop, steering, actions, background injection (chat.defer / chat.inject), fast starts (preload, Head Start via @trigger.dev/sdk/chat-server), context resilience (compaction, recovery boot, OOM, large payloads), chat.local run-scoped state, offline testing with mockChatAgent, or prerelease/version upgrades. For the everyday chat.agent({...}) definition and the useTriggerChatTransport happy path, use the trigger-authoring-chat-agent skill instead.4---5
6# chat.agent — advanced & operational
7
8The full, version-pinned reference ships **inside your installed `@trigger.dev/sdk`**. Read it before writing code — it always matches the SDK version in this project, so it never drifts:
9
10- **Skill:** `node_modules/@trigger.dev/sdk/skills/trigger-chat-agent-advanced/SKILL.md` — Sessions primitive, custom transports/wire protocol, sub-agents, HITL, steering, actions, background injection, fast starts, resilience (compaction/recovery/OOM/large payloads), `chat.local`, testing, upgrades.
11- **Docs:** the full, version-pinned docs ship bundled at `node_modules/@trigger.dev/sdk/docs/ai-chat/` (including `patterns/` for HITL, sub-agents, sessions); the skill above lists the exact pages it draws from in its `sources:` frontmatter. Grep for an API, e.g. `grep -rl "mockChatAgent" node_modules/@trigger.dev/sdk/docs/`.
12
13If those paths don't exist, `@trigger.dev/sdk` isn't installed yet — install it first. In a non-hoisted layout, resolve the package with `node -p "require.resolve('@trigger.dev/sdk/package.json')"` and read `skills/` + `docs/` beside it.
14
15## Common mistakes
16
17- **CRITICAL: sending a follow-up by re-POSTing `POST /api/v1/sessions`.**
18 ```ts
19 // Wrong - a cached re-POST silently drops basePayload.message; basePayload is trigger config, not a channel
20 await fetch("/api/v1/sessions", { method: "POST", body: JSON.stringify({ ...createBody }) });
21 // Correct - append to the session's input channel
22 await fetch(`/realtime/v1/sessions/${id}/in/append`, { method: "POST", body: JSON.stringify({ kind: "message", payload }) });
23 ```
24
25- **Using the wrong token for `.in` / `.out`.** Use `publicAccessToken` from the create response
26 body (session-scoped). The `x-trigger-jwt` response header is run-scoped and cannot subscribe.
27
28- **Initializing `chat.local` in `onChatStart`.** It is skipped on continuation runs, so `run()`
29 crashes with `chat.local can only be modified after initialization`. Init in `onBoot`.
30
31- **`chat.defer` for the message-history write.** A mid-stream refresh would read `[]`. `await` that
32 write inline before the model streams; reserve `chat.defer` for analytics, audit, cache warming.
33
34- **Giving the HITL tool an `execute`.** `streamText` calls it immediately. Leave it execute-less;
35 the frontend supplies the answer via `addToolOutput` + `sendAutomaticallyWhen`.
36
37- **Declaring sub-agent / heavy tools only on `streamText`.** Also declare them on
38 `chat.agent({ tools })` (or pass to `convertToModelMessages(uiMessages, { tools })` in a custom
39 agent) so `toModelOutput` re-applies on every turn.
40
41- **Importing heavy-execute tools into the Head Start route module.** This is a build-time import
42 chain problem; runtime strip helpers do not fix it. Keep schemas in an `ai` + `zod`-only module.
43
44- **Returning a megabyte tool output on the stream.** One `tool-output-available` record over ~1 MiB
45 throws `ChatChunkTooLargeError`. Persist to your store, write the row first, then emit only an id.
46
47- **Setting `X-Peek-Settled: 1` on the active-send path.** It races the new turn's first chunk and
48 closes the stream early. Use it only on reconnect-on-reload paths.
49
50> Note on docs vocabulary: agent-side examples in some docs still use the legacy
51> `trigger:turn-complete` chunk type. That is the agent-emit vocabulary. A custom **reader** must
52> filter on the `trigger-control` header, not on `chunk.type`.
53>
54> MCP-driven agent chats (`list_agents`, `start_agent_chat`, `send_agent_message`,
55> `close_agent_chat`) are MCP server tools used from Claude Code / Cursor, not importable SDK
56> functions. See `/mcp-tools#agent-chat-tools`.
57
58## References
59
60Sibling skills: **trigger-authoring-chat-agent** (the everyday `chat.agent({...})` happy path), **trigger-authoring-tasks** and **trigger-realtime-and-frontend** (task + frontend foundations).
gabrielmoreira