Anatomy of an agent - Trigger.dev

A chat agent is three parts: a long-lived agent task that runs the turn loop, a durable Session carrying messages in and the response stream out, and a frontend transport that plugs the session into useChat. The pages in this section each own one part of that picture. This page is the map — if you’d rather read mechanics end to end, skip to How it works. Everything below maps onto one annotated agent:

trigger/my-agent.ts

import { chat } from "@trigger.dev/sdk/ai";
import { streamText, stepCountIs } from "ai";
import { anthropic } from "@ai-sdk/anthropic";

export const myAgent = chat.agent({
  id: "my-agent",

  // Tools declared on the config survive history re-conversion
  // across turns — see Tools.
  tools: { searchDocs },

  // Hooks fire around each turn: validation, persistence,
  // post-turn work — see Lifecycle hooks.
  onTurnComplete: async ({ responseMessage }) => {
    await db.messages.save(responseMessage);
  },

  // The turn loop. Messages arrive accumulated; you stream back.
  // Options, levels, and alternatives — see Backend.
  run: async ({ messages, tools, signal }) =>
    streamText({
      ...chat.toStreamTextOptions({ tools }),
      model: anthropic("claude-sonnet-4-5"),
      messages,
      abortSignal: signal,
      stopWhen: stepCountIs(15),
    }),
});

The frontend side is one hook — useTriggerChatTransport connects useChat to the agent’s session, no API routes (Frontend). Underneath, the conversation lives on a Session: a pair of durable streams keyed on your chatId that survives refreshes, deploys, and run boundaries.

Where each part is covered

Part	Page
`chat.agent()` options, the turn loop, piping	Backend
Hooks around each turn (`onTurnComplete`, hydration)	Lifecycle hooks
Declaring tools, typed payloads, `toModelOutput`	Tools
`useChat` wiring, tokens, starting sessions	Frontend
Driving a chat from your server instead of a browser	Server-side chat
The durable substrate under every agent	Sessions
Per-run typed state inside the loop	chat.local
Type-safe payloads, client data, and messages	Types
Building without the managed lifecycle	Custom agents
End-to-end mechanics: what survives a refresh and why	How it works

Beyond this section: Features covers opt-in capabilities (Head Start, compaction, steering, actions), and Patterns covers production recipes (sub-agents, HITL approvals, persistence, recovery).

​Where each part is covered

Where each part is covered