Trigger.dev完全ガイド｜AIエージェント長時間タスク実装

記事ファイルが見つからないため、提供されたHTML（冒頭部分）に対してh3を追加した構造強化版を出力します。残りのh2セクション（7〜14個目）は提供されていないため、表示された部分のみ対応します。

「AIエージェントのタスクが途中でタイムアウトした」「OpenAI APIがレート制限で落ちたのに、最初からやり直しになった」——こんな経験はないでしょうか。

VercelやAWS Lambdaのサーバーレス環境では、実行時間に厳しい上限があります。AIエージェントが得意とする「スクレイピング→LLM処理→データ保存」のような多段タスクを信頼性高く動かすには、既存の関数実行基盤では限界があるのが現実です。

この記事では、その問題を解決するOSSプラットフォームTrigger.devを解説します。Durable Executionの設計思想から、2026年にGAになったv4の新機能、LLM APIを呼び出すタスクの実装パターンまで、コピペ可能なコードで紹介していきます。

Trigger.devとは何か

プラットフォームの概要とOSS体制

Trigger.devは、バックグラウンドジョブ・AIエージェント・自動化ワークフローをデプロイするためのOSS Durable Executionプラットフォームです。2022年創業のアイルランド発スタートアップで、GitHubスター数は14,000以上（2026年5月時点）。ライセンスはApache 2.0で、セルフホストも可能です。

タイムアウトなしの実行が解決する課題

最大の特徴は「タイムアウトなしの実行」です。AWS LambdaやVercel Functionsは最大15〜900秒の制限がありますが、Trigger.devではタスクを一時停止・再開できる仕組みにより、理論上は無制限に長いタスクを走らせられます。

Durable Executionとは

Durable Execution（耐久実行）とは、タスクの実行状態をチェックポイントとして保存しておき、障害・タイムアウト・意図的な一時停止があっても、その時点から再開できる仕組みです。

Trigger.devはCRIU（Checkpoint/Restore In Userspace）技術を使い、タスクのメモリ・CPUレジスタ・ファイルディスクリプタをそのままスナップショットします。再起動後はスナップショットをロードするだけで、コードは中断した行から続きを実行します。

インストールとプロジェクト初期化

CLIによるプロジェクト作成

Trigger.devはCLIとSDKで構成されています。まずNode.js 18以上の環境でプロジェクトを初期化します。

# CLI初期化（既存プロジェクトに追加する場合）
npx trigger.dev@latest init

# 新規プロジェクトを作成する場合
npx trigger.dev@latest create-project --name my-agent

CLIがインタラクティブに設定をガイドします。TypeScriptプロジェクトであれば、trigger.config.ts と src/trigger/ ディレクトリが自動作成されます。

SDK・AI連携パッケージの導入

# SDKのインストール
npm install @trigger.dev/sdk@latest

# AI SDKとの統合（Vercel AI SDK v6対応）
npm install @trigger.dev/ai @ai-sdk/openai

ローカル開発サーバーの起動とデプロイ

# ローカル開発サーバーの起動
npx trigger.dev@latest dev

ローカル開発時は、CLIがトンネルを張ってTrigger.dev Cloudと接続します。本番デプロイは npx trigger.dev@latest deploy 一発です。

基本タスクの定義

task()関数によるタスク作成

Trigger.devのタスクは task() 関数で定義します。TypeScriptで書くだけで、あとは自動的にデプロイ・管理されます。

// src/trigger/hello-world.ts
import { task } from "@trigger.dev/sdk/v3";

export const helloWorldTask = task({
  id: "hello-world",
  run: async (payload: { message: string }) => {
    console.log(`受信メッセージ: ${payload.message}`);
    return { result: `処理完了: ${payload.message}` };
  },
});

アプリケーションからのトリガー方法

タスクをトリガーするには、アプリケーションコードから trigger() を呼ぶだけです。

// Next.js API Routeやサーバーアクションから
import { helloWorldTask } from "@/trigger/hello-world";

const handle = await helloWorldTask.trigger({ message: "こんにちは" });
console.log(`Run ID: ${handle.id}`);

スケジュールタスク（Cron）

定期実行が必要なレポート生成や監視処理には、scheduleTask() を使います。

// src/trigger/daily-report.ts
import { scheduleTask } from "@trigger.dev/sdk/v3";

export const dailyReportTask = scheduleTask({
  id: "daily-report",
  cron: "0 9 * * 1-5",   // 平日9時に実行
  run: async (payload) => {
    // レポート生成ロジック
    const report = await generateReport(payload.lastTimestamp);
    await sendSlackNotification(report);
  },
});

Run Hierarchies — 親子タスクで複雑なフローを構成する

triggerAndWait()による子タスク呼び出し

実際のAIエージェントでは、複数のタスクをチェーンさせることがほとんどです。Trigger.devは親タスクから子タスクを triggerAndWait() で呼び出すことで、ツリー構造のワークフローを簡単に構築できます。

// src/trigger/research-agent.ts
import { task } from "@trigger.dev/sdk/v3";
import { fetchUrlTask } from "./fetch-url";
import { summarizeTask } from "./summarize";

export const researchAgentTask = task({
  id: "research-agent",
  run: async (payload: { urls: string[] }) => {
    // 子タスクを並列実行
    const fetchResults = await Promise.all(
      payload.urls.map((url) =>
        fetchUrlTask.triggerAndWait({ url })
      )
    );

    // 全ての取得が完了してから要約
    const summaries = await Promise.all(
      fetchResults.map((r) =>
        summarizeTask.triggerAndWait({ content: r.output.content })
      )
    );

    return { summaries: summaries.map((s) => s.output) };
  },
});

CRIUチェックポイントによるリソース最適化

triggerAndWait() は子タスクの完了を待機しますが、この「待機中」はCRIUチェックポイントが作られ、インフラリソースは消費されません。コストを抑えながら複雑なフローを書けます。

Idempotency（冪等性）とRetry戦略

冪等性キーによる重複実行の防止

AIエージェントで一番困るのが「どこまで処理したかわからなくなる」状況です。Trigger.devの冪等性キーはこれを解決します。

import { task, idempotencyKeys } from "@trigger.dev/sdk/v3";

export const processOrderTask = task({
  id: "process-order",
  retry: {
    maxAttempts: 5,
    factor: 2,
    minTimeoutInMs: 1000,
    maxTimeoutInMs: 30000,
  },
  run: async (payload: { orderId: string }) => {
    // 冪等性キーを設定 — 同じキーで2回呼ばれても1回しか実行しない
    const key = await idempotencyKeys.create(payload.orderId);

    const paymentResult = await chargePaymentTask.triggerAndWait(
      { orderId: payload.orderId },
      { idempotencyKey: key }
    );

    // 失敗した場合、retry設定に従って自動でリトライ
    if (!paymentResult.ok) {
      throw new Error(`Payment failed: ${paymentResult.error}`);
    }

    return paymentResult.output;
  },
});

指数バックオフによるリトライ設定

失敗が起きても、冪等性キーのおかげでリトライ時に決済が2重実行される心配がありません。retry オプションの factor と maxAttempts を調整することで、外部APIの特性に合わせた最適なリトライ間隔を設計できます。

LLM API呼び出しのDurable化パターン

OpenAI APIのDurableラップ実装

AIエージェント開発でもっとも実用的なパターンです。OpenAI APIの呼び出しをDurableにラップすることで、レート制限・ネットワーク障害・タイムアウトから安全に保護できます。

// src/trigger/llm-pipeline.ts
import { task } from "@trigger.dev/sdk/v3";
import OpenAI from "openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export const llmAnalysisTask = task({
  id: "llm-analysis",
  retry: {
    maxAttempts: 10,
    // OpenAIのレート制限に合わせた指数バックオフ
    factor: 2,
    minTimeoutInMs: 2000,
    maxTimeoutInMs: 120000,
  },
  run: async (payload: { documents: string[] }) => {
    const results = [];

    for (const [index, doc] of payload.documents.entries()) {
      // 各ドキュメントを冪等性キーで保護
      const key = await idempotencyKeys.create(`doc-${index}-${doc.slice(0, 50)}`);

      const response = await openai.chat.completions.create({
        model: "gpt-4o",
        messages: [
          { role: "system", content: "あなたは文書分析の専門家です。" },
          { role: "user", content: doc },
        ],
      });

      results.push({
        index,
        analysis: response.choices[0].message.content,
      });
    }

    return { results };
  },
});

大量ドキュメント処理での中断再開

このパターンにより、100件のドキュメントを処理中にAPIエラーが起きた場合も、50件目から再開できます。

Vercel AI SDKとの統合（v6対応）

Vercel AI SDK v6を使えば、モデル切り替えやストリーミング処理もTrigger.devのDurable環境内でシームレスに利用できます。

import { task } from "@trigger.dev/sdk/v3";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

export const aiPipelineTask = task({
  id: "ai-pipeline",
  run: async (payload: { prompt: string }) => {
    const { text } = await generateText({
      model: openai("gpt-4o"),
      prompt: payload.prompt,
    });
    return { text };
  },
});

—

対応結果の要約:

📚 公式リファレンス・出典

• 総務省 情報通信白書
• 経産省 AI関連政策
• 内閣府 AI戦略