wehub-resource-sync
71 lines
4.6 KiB
Markdown
71 lines
4.6 KiB
Markdown
---
|
|
name: trigger-chat-agent-advanced
|
|
description: >
|
|
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.
|
|
type: core
|
|
library: trigger.dev
|
|
---
|
|
|
|
# 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).
|