convex-agents-workflows

Sstobo's avatarfrom Sstobo

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.

⭐5stars🔀0forks📁View on GitHub🕐Updated Oct 18, 2025⬇️2downloads

When & Why to Use This Skill

This Claude skill provides a robust framework for orchestrating multi-step agent workflows with durable execution guarantees. It solves the challenge of reliability in complex AI operations by offering automatic retries, failure recovery, and idempotency, ensuring that long-running tasks survive server restarts and multiple agents coordinate seamlessly without losing state.

Use Cases

  • Complex Research Pipelines: Automating multi-stage tasks like initial web research, followed by data analysis, and concluding with comprehensive report generation.
  • Multi-Agent Coordination: Managing collaborative workflows where different specialized agents must pass data and tasks to one another to achieve a common goal.
  • Resilient Long-Running Tasks: Executing background operations that take significant time and must remain stable despite infrastructure interruptions or server failures.
  • Idempotent Workflow Execution: Preventing duplicate work or redundant API calls by ensuring that retried steps do not repeat actions that have already succeeded.
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