Convex Agents Workflows

Purpose

Provides durable, reliable execution of complex agent workflows. Workflows ensure multi-step operations complete reliably, survive server failures, and maintain idempotency.

When to Use This Skill

• Building multi-step agent operations (research → analysis → report)
• Coordinating multiple agents working together
• Long-running operations that need to survive server restarts
• Ensuring idempotency (no duplicate work even if retried)
• Complex applications requiring durable execution guarantees

Setup

Configure Workflow component in convex.config.ts:

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;

Define a Workflow

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;
  },
});

Multi-Agent Workflows

Orchestrate multiple agents:

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 };
  },
});

Key Principles

• Durability: Workflows survive server restarts
• Idempotency: Same workflow can be safely retried
• Atomicity: Each step either completes fully or retries
• Composability: Steps can call other workflows or actions

Next Steps

• See fundamentals for agent setup
• See tools for agents that call functions
• See context for workflow-aware context