SECURITY REVIEW
Not yet assessed
Review the original instructions and requested permissions before installing.
No security review is available for this catalog entry yet.
Community / AGENT SKILL
trigger-chat-agent-advanced
0
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.
Understand the trade-offs.
SKILL QUALITY
Not yet assessed
How clearly the skill guides your agent, how complete its workflow is, and how you can check the outcome.
No quality assessment is available for this catalog entry yet.
The full skill.
Original instructions from the publisher’s SKILL.md
# 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`.**
```ts
// 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).