Authoring a chat.agent

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-authoring-chat-agent/SKILL.md — the per-turn run loop, the managed streamText, the two server actions, typed tools/data parts, and the React transport.
• Docs: the full, version-pinned docs ship bundled at node_modules/@trigger.dev/sdk/docs/ai-chat/; the skill above lists the exact pages it draws from in its sources: frontmatter. Grep for an API, e.g. grep -rl "toStreamTextOptions" 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: calling the streamText imported from ai.

  // Wrong - compaction / steering / background injection silently no-op
  import { streamText } from "ai";
  run: async ({ messages, signal }) => streamText({ model, messages, abortSignal: signal });
  // Correct - the run argument's streamText carries the managed options
  run: async ({ messages, signal, streamText }) => streamText({ model, messages, abortSignal: signal });

  The SDK's one carries the prepareStep behind compaction, mid-turn steering and background injection, the system prompt from chat.prompt() or chat.agent({ system }), the registry-resolved model, and telemetry. The imported one carries none of it, with no error. ...chat.toStreamTextOptions() does the same job by hand, and is what a custom agent has to use, since it has no run argument. A chat.headStart route gets a bound streamText too, and there it also owns messages, stopWhen and abortSignal.

• Declaring tools only on streamText. Also declare them on chat.agent({ tools }), read them back from run, and pass that set as tools. Otherwise each tool's toModelOutput runs on turn 1 but is dropped when history is re-converted on later turns.

• Not forwarding signal for stop. Without abortSignal: signal, Stop updates the UI but the model keeps generating server-side.

• Initializing chat.local in onChatStart. Initialize it in onBoot. onChatStart fires once per chat, so continuation runs skip it and crash with chat.local can only be modified after initialization. onBoot fires on every fresh worker.

• Minting tokens in the browser. Never expose the environment secret key client-side. Mint via the two server actions; the transport calls them.

• Clearing lastEventId on chat.endRun(). Keep the cursor for the Session lifetime; clear it only when the Session itself closes. It is sessionId-keyed, so clearing forces a resubscribe from seq_num=0 that can hit the prior turn's stale turn-complete and close the stream empty.

• Returning the raw error from uiMessageStreamOptions.onError. It leaks internals (keys, stack traces). Return a sanitized string instead.

References

Sibling skills: trigger-chat-agent-advanced (Sessions primitive, custom transports, sub-agents, HITL, fast starts, resilience, testing, upgrades), trigger-authoring-tasks and trigger-realtime-and-frontend (the task + frontend foundations chat builds on).