Convex Agents Workflows

目的

複雑なエージェントのワークフローを、堅牢かつ確実に実行できるようにします。ワークフローにより、複数ステップの操作を確実に完了し、サーバー障害から復旧し、冪等性を維持できます。

このスキルを使用する場面

• 複数ステップのエージェント操作を構築する（調査 → 分析 → レポート）
• 複数のエージェントの連携を調整する
• サーバーの再起動後も継続する必要がある長時間実行の操作
• 冪等性を確保する（再試行しても作業が重複しない）
• 確実な実行保証が求められる複雑なアプリケーション

セットアップ

convex.config.ts で Workflow コンポーネントを設定します。

import { defineApp } from "convex/server";
import agent from "@convex-dev/agent/convex.config";
import workflow from "@convex-dev/workflow/convex.config";

const app = defineApp();
app.use(agent);
app.use(workflow);

export default app;

ワークフローを定義する

import { WorkflowManager } from "@convex-dev/workflow";

const workflow = new WorkflowManager(components.workflow);

export const simpleAgentFlow = workflow.define({
  id: "simple-flow",
  args: { userId: v.string(), prompt: v.string() },
  handler: async (step, { userId, prompt }) => {
    // Step 1: Create thread
    const { threadId } = await step.runMutation(
      internal.agents.createThreadMutation,
      { userId }
    );

    // Step 2: Generate response
    const response = await step.runAction(
      internal.agents.generateTextAction,
      { threadId, prompt }
    );

    return response;
  },
});

マルチエージェントワークフロー

複数のエージェントをオーケストレーションします。

export const researchFlow = workflow.define({
  id: "research",
  args: { topic: v.string(), userId: v.string() },
  handler: async (step, { topic, userId }) => {
    const { threadId: researchId } = await step.runMutation(
      internal.agents.createThreadMutation,
      { userId, title: `Research: ${topic}` }
    );

    const research = await step.runAction(
      internal.agents.generateTextAction,
      { threadId: researchId, prompt: `Research: ${topic}` }
    );

    const { threadId: analysisId } = await step.runMutation(
      internal.agents.createThreadMutation,
      { userId, title: `Analysis: ${topic}` }
    );

    const analysis = await step.runAction(
      internal.agents.generateTextAction,
      { threadId: analysisId, prompt: `Analyze: ${research}` }
    );

    return { research, analysis };
  },
});

主な原則

• 耐久性：ワークフローはサーバーの再起動後も継続します
• 冪等性：同じワークフローを安全に再試行できます
• アトミック性：各ステップは完全に完了するか、再試行されます
• 合成可能性：ステップから別のワークフローやアクションを呼び出せます

次のステップ

• エージェントのセットアップについては fundamentals を参照してください
• 関数を呼び出すエージェントについては tools を参照してください
• ワークフロー対応コンテキストについては context を参照してください