You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(ai-agents): add chat.agent guide and refresh the AI agent guides (#4524)
## Summary
Adds a "Build a chat agent" guide to the AI agents section, surfaces the
ClickHouse chat agent example in the guides index and the AI agents
overview,
and refreshes the five existing workflow guides so their code is
current.
## Details
The pattern guides (prompt chaining, routing, parallelization,
orchestrator,
evaluator-optimizer) still used retired models and dated APIs. Updated
them to
current Anthropic Claude models (claude-haiku-4-5 for lightweight
classifier
roles, claude-sonnet-4-5 for the main work) and modernized the code:
- route-question uses generateObject for the routing decision instead of
generateText plus manual JSON parsing.
- verify-news-article uses ModelMessage in place of the renamed
CoreMessage.
- Fixed translate-and-refine discarding its recursive refinement result,
so
refined translations never returned to the caller.
- Fixed an invalid JSON test payload in generate-translate-copy.
The pattern concepts are unchanged; only the example code was stale.
description: "Create a durable, multi-turn chat agent with chat.agent(), then add tools to it like any AI SDK agent."
5
+
---
6
+
7
+
## Overview
8
+
9
+
Build a **durable, multi-turn chat agent**. A durable session owns the conversation, streams tokens to your UI, and stays alive across many back-and-forth messages. The other guides in this section are one-shot workflows (trigger a task, run a fixed sequence of LLM calls, return a result); a chat agent instead owns the session for its whole lifetime.
10
+
11
+
[`chat.agent()`](/ai-chat/overview) handles the queuing, retries, resumability and streaming for you. You write the model call, Trigger.dev owns the session. For the full feature set (sessions, fast starts, compaction, sub-agents, the frontend transport), see the [AI chat docs](/ai-chat/overview).
12
+
13
+
## A minimal agent
14
+
15
+
Define an agent with `chat.agent()`. The `run` function receives the conversation `messages` (already converted from the frontend's `UIMessage[]`) and an abort `signal`. Return a `StreamTextResult` and it's piped to the frontend automatically.
16
+
17
+
```typescript trigger/chat.ts
18
+
import { chat } from"@trigger.dev/sdk/ai";
19
+
import { anthropic } from"@ai-sdk/anthropic";
20
+
import { streamText, stepCountIs } from"ai";
21
+
22
+
exportconst myChat =chat.agent({
23
+
id: "my-chat",
24
+
run: async ({ messages, signal }) => {
25
+
returnstreamText({
26
+
// Spread chat.toStreamTextOptions() FIRST: it wires up prepareStep
27
+
// (compaction, steering, background injection) and telemetry.
28
+
...chat.toStreamTextOptions(),
29
+
model: anthropic("claude-sonnet-4-5"),
30
+
messages,
31
+
abortSignal: signal,
32
+
stopWhen: stepCountIs(15),
33
+
});
34
+
},
35
+
});
36
+
```
37
+
38
+
<Warning>
39
+
Always spread `chat.toStreamTextOptions()` into your `streamText` call, and spread it first. It
40
+
wires up the `prepareStep` callback that drives compaction, mid-turn steering and background
41
+
injection. Those features silently no-op if the spread is missing.
42
+
</Warning>
43
+
44
+
## Add tools
45
+
46
+
A chat agent uses tools exactly like any other AI SDK agent. Declare them on the config so their results survive across turns, then pass the `tools` you receive in `run` straight to `streamText`:
// Declared here so tool results survive history re-conversion across turns.
63
+
tools: { getCurrentTime },
64
+
run: async ({ messages, tools, signal }) => {
65
+
returnstreamText({
66
+
// Pass tools INTO toStreamTextOptions (not separately to streamText): it
67
+
// merges them with any auto-injected skill tools and sets streamText's
68
+
// `tools`. Passing tools separately after the spread drops the skill tools.
69
+
...chat.toStreamTextOptions({ tools }),
70
+
model: anthropic("claude-sonnet-4-5"),
71
+
messages,
72
+
stopWhen: stepCountIs(15),
73
+
abortSignal: signal,
74
+
});
75
+
},
76
+
});
77
+
```
78
+
79
+
Swap `getCurrentTime` for whatever your agent needs to do: query a database, call an API, or trigger another Trigger.dev task. See [Tools](/ai-chat/tools) for how tool results are persisted and replayed across turns.
80
+
81
+
## Wire up the frontend
82
+
83
+
The browser talks to Trigger.dev directly through the [chat transport](/ai-chat/frontend), so there's no API route to maintain. Expose two server actions (one to start the session, one to mint a session-scoped token) and pass them to `useTriggerChatTransport`, then hand the transport to the AI SDK's `useChat`:
See the [Quick Start](/ai-chat/quick-start) for the complete frontend component.
105
+
106
+
## A full example
107
+
108
+
For a complete, real-world chat agent, see the ClickHouse chat agent example. It builds on everything above with generative UI, a versioned system prompt, and real tools against a live database.
Build a chat agent that answers questions about your ClickHouse data with charts, tables and maps
31
+
using `chat.agent()` and generative UI.
32
+
</Card>
25
33
<Card
26
34
icon="hand"
27
35
title="Human-in-the-loop workflow"
@@ -68,6 +76,20 @@ description: "Real world AI agent example tasks using Trigger.dev"
68
76
</Card>
69
77
</CardGroup>
70
78
79
+
## Chat agents
80
+
81
+
Build a durable, multi-turn chat agent with [`chat.agent()`](/ai-chat/overview). A durable session per conversation, with streaming and resumability handled for you.
82
+
83
+
<CardGroupcols={2}>
84
+
<Card
85
+
title="Chat agent"
86
+
icon="message-bot"
87
+
href="/guides/ai-agents/chat-agent"
88
+
>
89
+
Create a durable, multi-turn chat agent with `chat.agent()`, then add tools to it.
90
+
</Card>
91
+
</CardGroup>
92
+
71
93
## Agent fundamentals
72
94
73
95
These guides will show you how to set up different types of AI agent workflows with Trigger.dev. The examples take inspiration from Anthropic's blog post on [building effective agents](https://www.anthropic.com/research/building-effective-agents).
0 commit comments