convex-agents-workflows
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.
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