Convex Agents Workflows

name: "Convex Agents Workflows" description: "Orchestrates multi-step agent operations with durable execution, automatic retries, and recovery from failures. Use this for complex workflows that need to survive server restarts or coordinate multiple agents."

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