chat-agent
Build, migrate or debug AI chat agents on Trigger.dev (chat.agent, the chat transport, sessions, transcript storage, tool approvals, server, Slack and Linear callers). Use when a Trigger.dev project needs a chat assistant or agent, or code imports @trigger.dev/sdk/ai or @trigger.dev/sdk/chat.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- chat-agent
- description
- Build, migrate or debug AI chat agents on Trigger.dev (chat.agent, the chat transport, sessions, transcript storage, tool approvals, server, Slack and Linear callers). Use when a Trigger.dev project needs a chat assistant or agent, or code imports @trigger.dev/sdk/ai or @trigger.dev/sdk/chat.
- allowed-tools
- Bash(trigger-ctx *) Bash(node *trigger-ctx.mjs *) Bash(node *trigger-ctx.mjs" *) Bash(npx trigger.dev@latest whoami*) Bash(npx tsc --noEmit*) Bash(pnpm exec tsc --noEmit*) Bash(yarn tsc --noEmit*) Bash(bunx tsc --noEmit*)
- argument-hint
- [what the agent should do, or what is broken]
02 资源文件 10
- 参考文档playbooks/approvals-and-questions.md4.1 KB
- 参考文档playbooks/fast-first-reply.md3.9 KB
- 参考文档playbooks/greenfield.md4.6 KB
- 参考文档playbooks/long-conversations.md3.8 KB
- 参考文档playbooks/migrate-route-handler.md4.0 KB
- 参考文档playbooks/persistence.md4.1 KB
- 参考文档playbooks/resilience.md4.0 KB
- 参考文档playbooks/server-and-channel-callers.md4.8 KB
- 参考文档playbooks/sub-agents-tools-sandbox.md4.2 KB
- 参考文档playbooks/test-verify-ship.md4.3 KB
03 SKILL.md 正文
Trigger.dev: chat agents
A chat agent is a durable multi-turn assistant that survives refreshes, deploys, idle gaps and crashes. Three parts: the agent task (chat.agent, which owns the turn loop), a durable session (.in and .out streams keyed on chatId, outliving runs), and the frontend transport (useTriggerChatTransport feeding useChat). A run suspends after idleTimeoutInSeconds (30 s by default) and resumes the same process; continuation runs boot cold and fire onBoot.
Invariants (check every snippet; the plugin's edit checks enforce several)
- SDK ≥ 4.5.0. Older projects update first (
npx trigger.dev@latest update).needsApprovalneeds AI SDK 6 or newer. streamTextcomes fromrun's argument (run: async ({ messages, signal, streamText }) => …), not from"ai". The stock import silently loses compaction, steering and injection. Spreading...chat.toStreamTextOptions()into it is the supported alternative (and the only one in a custom agent).- Both server actions check ownership. The token action and the start-session action must verify that the signed-in user owns the
chatIdbefore minting anything. Never authorise fromclientData. Without this, one user can reach another user's chat. chat.localis initialised inonBoot(every fresh worker, continuations included), never inonChatStartoronPreload.- Declare tools on
chat.agent({ tools }), not only at thestreamTextcall, so each tool'stoModelOutputis re-applied across turns. - Persistence: the platform snapshot by default (a self-hosted instance needs
OBJECT_STORE_*), orstorage: TranscriptStoragewhen your database is the source of truth.hydrateMessagesis deprecated. The transcript format is roll-forward only, andcreateLoadTranscriptActionhas no tenant check of its own: wrap it. - Retries: keep
maxAttempts: 1;oomMachineis the only retry path; tools must be idempotent because OOM retries and regenerate replay them. - Approvals and questions: a question tool has no
execute; an approval usesneedsApprovalplusexecute.onActionreturns nothing orchat.turn(), never a response.
Anchor and discovery
Use the project facts in context (or trigger-ctx detect --brief): SDK version, ai major, frontend, Cloud or self-host. Infer first, ask second (at most two questions in the whole reply, next steps included, defaults for the rest; the repo usually answers):
| # | Ask only if not inferable | Changes | Infer from |
|---|---|---|---|
| C1 | Migrating an existing chat route, or new? | migrate-route-handler vs greenfield |
app/api/chat/route.ts, streamText + toUIMessageStreamResponse, resumable-stream, useChat |
| C2 | Who talks to the agent: a browser, Slack or Linear, other servers or agents? | transport vs AgentChat vs channels (slack()/linear(), SDK ≥ 4.8.0) |
@slack/*, webhook routes, a frontend present |
| C3 | Must chat history live in your database (list, search, edit, branch, audit)? | platform snapshot vs storage |
prisma or drizzle schema with chat tables |
| C4 | Do any tools have side effects that need approval? | needsApproval, idempotent tools |
an existing tools map; ai major |
| C5 | How do users authenticate, and who owns a chat? | the ownership check (mandatory) | next-auth, clerk, lucia, supabase |
| C6 | Is first-reply latency important? | Preload vs Head Start vs neither | a warm server route, a serverless host |
| C7 | Long conversations or very large tool outputs? | compaction, prompt caching, id references (about 1 MiB cap) | the domain (RAG, code, files) |
| C8 | Cloud or self-hosted? | baseURL; OBJECT_STORE_* |
the project facts |
Inferred without asking: the frontend (the React transport hook is React-only; other frameworks use the client protocol), the AI SDK major, the provider packages, the deploy host.
Choose the layer, the callers and the persistence
- Layer:
chat.agent(default) ·chat.createSession(your own per-turn code; no lifecycle hooks, actions or approvals; Head Start works with it since 4.5.0 even though theai-chat/backendcapability table still says no) ·chat.customAgentwith primitives (a custom protocol) · rawsessions(not chat-shaped). - Callers: a browser (React transport) · a server, script, Slack bot or another agent (
AgentChat; deterministicidto resume) · a non-React or non-TS client (the client protocol over REST/SSE) · Slack or Linear (slack()/linear()channels, SDK ≥ 4.8.0, generally available; below that, offer the update or callAgentChatfrom your own handler). - Persistence: snapshot (default) ·
storage: TranscriptStorage(runTranscriptStorageTeststo verify) · never newhydrateMessages.
Playbooks (read one, at ${CLAUDE_SKILL_DIR}/playbooks/<file>)
| Situation | File |
|---|---|
| a new chat agent from scratch | greenfield.md |
an existing useChat + route handler to move |
migrate-route-handler.md |
| history in your database, list/search/edit | persistence.md |
| tool approvals, questions to the user, undo/edit actions | approvals-and-questions.md |
| Slack, Linear, server callers, other agents | server-and-channel-callers.md |
| the first reply is slow | fast-first-reply.md |
| long conversations, big tool outputs, caching | long-conversations.md |
| crashes, OOM, recovery, deploys mid-conversation | resilience.md |
| sub-agents, skills, code sandboxes | sub-agents-tools-sandbox.md |
| tests, a live smoke test, readiness to ship | test-verify-ship.md |
Verify before you write, answer in the bridge format
Resolve every API name with trigger-ctx docs <topic or name> (a name returns whether the installed types declare it, any @deprecated note, and the pinned-doc file:line) and read the local pinned page (node_modules/@trigger.dev/sdk/docs/ai-chat/…) or the web .md; the chat API changes fast (changelog: https://trigger.dev/docs/ai-chat/changelog). If no docs tier is reachable, still answer from the playbook and list every API name you could not check as unverified; never refuse for lack of docs. Answer as: You're building X. Y fits because Z (not W, because …). Minimal shape (≤ 15 lines). Watch out for (≤ 3). Docs: local path · URL. Name the environment when you test (dev unless the user says otherwise); a live smoke test is MCP list_agents → start_agent_chat → send_agent_message → close_agent_chat, and start_agent_chat in prod spends real LLM budget: ask first.
04 同仓库更多 Skills
ship
Deploy Trigger.dev tasks (trigger deploy) to staging, prod or a preview branch with a preflight, the right CI or integration pipeline, an explicit --env, and a verification step. Use when asked to deploy, ship or release the Trigger.dev tasks or jobs. Not for deploying the app itself to Vercel, Fly or another host.
new
Add one capability to an existing Trigger.dev project (a task, a schedule, a progress UI, an approval step, a webhook handler) and prove it runs.
init
Set up Trigger.dev in this repository with a short discovery, an explicit architecture decision, and a first task proven to run.
doctor
Check the Trigger.dev toolchain around this project (Node, CLI login and profile, MCP server, versions, duplicate official skills, self-host target, plugin install scope) and report what to fix.
diagnose
Find out why Trigger.dev runs or deploys misbehave (stuck QUEUED or PENDING_VERSION, failed, timed out, crashed or OOM, schedules not firing, 429s, CI deploy failures, chat history lost). Use when a Trigger.dev project shows an error, a run id such as run_abc123, or the user says a task did not run.
audit
Review a Trigger.dev codebase against the plugin's rule catalog (stale APIs, silent-failure patterns, config, deploy, cost) and write a findings report; optionally apply safe fixes.