wehub-resource-sync
158 lines
6.8 KiB
Plaintext
158 lines
6.8 KiB
Plaintext
---
|
|
title: "Quick Start"
|
|
sidebarTitle: "Quick Start"
|
|
description: "Get a working AI agent in 3 steps — define an agent, generate a token, and wire up the frontend."
|
|
---
|
|
|
|
These steps assume you already have a Trigger.dev project with the SDK installed and the CLI authenticated — if you don't, follow [Manual setup](/manual-setup) (or `npx trigger.dev@latest init` in an existing project) first. You should be able to run `pnpm exec trigger dev` from your project root before continuing.
|
|
|
|
The chat surface works with Vercel AI SDK **v5, v6, or v7**; install whichever major you want. On **v7**, also install `@ai-sdk/otel` so your model calls are traced (the SDK registers it for you). See [compatibility](/ai-chat/reference#compatibility) for the full matrix.
|
|
|
|
<Steps>
|
|
<Step title="Define a chat agent">
|
|
Use `chat.agent` from `@trigger.dev/sdk/ai` to define an agent that handles chat messages. The `run` function receives `ModelMessage[]` (already converted from the frontend's `UIMessage[]`) — pass them directly to `streamText`.
|
|
|
|
If you return a `StreamTextResult`, it's **automatically piped** to the frontend.
|
|
|
|
```ts trigger/chat.ts
|
|
import { chat } from "@trigger.dev/sdk/ai";
|
|
import { streamText, stepCountIs } from "ai";
|
|
import { anthropic } from "@ai-sdk/anthropic";
|
|
|
|
export const myChat = chat.agent({
|
|
id: "my-chat",
|
|
run: async ({ messages, signal }) => {
|
|
return streamText({
|
|
// Spread chat.toStreamTextOptions() FIRST — it wires up
|
|
// prepareStep (compaction, steering, background injection),
|
|
// the system prompt set via chat.prompt(), and telemetry.
|
|
// Skipping this is the single most common cause of subtle
|
|
// bugs (silent broken compaction, missing steering, etc.).
|
|
...chat.toStreamTextOptions(),
|
|
model: anthropic("claude-sonnet-4-5"),
|
|
messages,
|
|
abortSignal: signal,
|
|
stopWhen: stepCountIs(15),
|
|
});
|
|
},
|
|
});
|
|
```
|
|
|
|
<Warning>
|
|
**Always spread `chat.toStreamTextOptions()` into your `streamText` call.** It wires up the `prepareStep` callback that drives compaction, mid-turn steering, and background injection — features that silently no-op if the spread is missing. Spread it **first** so any explicit overrides (e.g. a custom `prepareStep`) win.
|
|
</Warning>
|
|
|
|
<Tip>
|
|
For a **custom** [`UIMessage`](https://sdk.vercel.ai/docs/reference/ai-sdk-core/ui-message) subtype (typed `data-*` parts, tool map, etc.), define the agent with [`chat.withUIMessage<...>().agent({...})`](/ai-chat/types) instead of `chat.agent`.
|
|
</Tip>
|
|
|
|
</Step>
|
|
|
|
<Step title="Add two server actions">
|
|
On your server (e.g. as Next.js server actions), expose two helpers the transport will call: one that creates the chat session, and one that mints a fresh session-scoped access token for refresh.
|
|
|
|
```ts app/actions.ts
|
|
"use server";
|
|
|
|
import { auth } from "@trigger.dev/sdk";
|
|
import { chat } from "@trigger.dev/sdk/ai";
|
|
|
|
// Creates the Session row + triggers the first run, returns the
|
|
// session PAT. Idempotent on (env, chatId) so concurrent calls
|
|
// converge to the same session.
|
|
export const startChatSession = chat.createStartSessionAction("my-chat");
|
|
|
|
// Pure mint — fresh session-scoped PAT for an existing session.
|
|
// The transport calls this on 401/403 to refresh.
|
|
export async function mintChatAccessToken(chatId: string) {
|
|
return auth.createPublicToken({
|
|
scopes: {
|
|
read: { sessions: chatId },
|
|
write: { sessions: chatId },
|
|
},
|
|
expirationTime: "1h",
|
|
});
|
|
}
|
|
```
|
|
|
|
The browser never holds your environment's secret key — both helpers run on your server, where customer-side authorization (per-user, per-plan, etc.) lives alongside any DB writes you want to pair with session creation.
|
|
|
|
</Step>
|
|
|
|
<Step title="Use in the frontend">
|
|
Use the `useTriggerChatTransport` hook from `@trigger.dev/sdk/chat/react` to create a memoized transport instance, then pass it to `useChat`. Wire both server actions into the transport's `accessToken` and `startSession` callbacks.
|
|
|
|
The example below uses the Next.js `@/*` path alias for imports from `@/trigger/chat` and `@/app/actions`. If you're not using Next.js (or haven't configured the alias), swap them for relative imports.
|
|
|
|
```tsx app/components/chat.tsx
|
|
"use client";
|
|
|
|
import { useState } from "react";
|
|
import { useChat } from "@ai-sdk/react";
|
|
import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
|
|
import type { myChat } from "@/trigger/chat";
|
|
import { mintChatAccessToken, startChatSession } from "@/app/actions";
|
|
|
|
export function Chat() {
|
|
const transport = useTriggerChatTransport<typeof myChat>({
|
|
task: "my-chat",
|
|
accessToken: ({ chatId }) => mintChatAccessToken(chatId),
|
|
startSession: ({ chatId, clientData }) =>
|
|
startChatSession({ chatId, clientData }),
|
|
});
|
|
|
|
const { messages, sendMessage, stop, status } = useChat({ transport });
|
|
const [input, setInput] = useState("");
|
|
|
|
return (
|
|
<div>
|
|
{messages.map((m) => (
|
|
<div key={m.id}>
|
|
<strong>{m.role}:</strong>
|
|
{m.parts.map((part, i) =>
|
|
part.type === "text" ? <span key={i}>{part.text}</span> : null
|
|
)}
|
|
</div>
|
|
))}
|
|
|
|
<form
|
|
onSubmit={(e) => {
|
|
e.preventDefault();
|
|
if (input.trim()) {
|
|
sendMessage({ text: input });
|
|
setInput("");
|
|
}
|
|
}}
|
|
>
|
|
<input
|
|
value={input}
|
|
onChange={(e) => setInput(e.target.value)}
|
|
placeholder="Type a message..."
|
|
/>
|
|
<button type="submit" disabled={status === "streaming"}>
|
|
Send
|
|
</button>
|
|
{status === "streaming" && (
|
|
<button type="button" onClick={stop}>
|
|
Stop
|
|
</button>
|
|
)}
|
|
</form>
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Next steps
|
|
|
|
- [Backend](/ai-chat/backend) — Lifecycle hooks, persistence, session iterator, raw task primitives
|
|
- [Tools](/ai-chat/tools): Declare tools so `toModelOutput` survives across turns, typed in `run()`
|
|
- [Frontend](/ai-chat/frontend) — Session management, client data, reconnection
|
|
- [Types](/ai-chat/types) — `chat.withUIMessage`, `InferChatUIMessage`, and related typing
|
|
- [`chat.local`](/ai-chat/chat-local) — Per-run typed state across hooks, run, tools, subtasks
|
|
- [Sub-agents pattern](/ai-chat/patterns/sub-agents) — Subtask-as-tool, `target: "root"` streaming, `ai.toolExecute` helpers
|
|
- [Background injection](/ai-chat/background-injection) — `chat.inject()` and `chat.defer()` for between-turn work
|