Agent skill
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.
Install this agent skill to your Project
npx add-skill https://github.com/Sstobo/convex-skills/tree/main/convex-agents-workflows
SKILL.md
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
Sstobo/convex-skills
Convex Agents Streaming
Streams agent responses in real-time to clients without blocking. Use this for responsive UIs, long-running generations, and asynchronous streaming to multiple clients.
Sstobo/convex-skills
Convex Agents Files
Handles file uploads, image attachments, and media processing in agent conversations. Use this when agents analyze images, process documents, or generate files.
Sstobo/convex-skills
convex-actions-general
This skill should be used when working with Convex actions, HTTP endpoints, validators, schemas, environment variables, scheduling, file storage, and TypeScript patterns. It provides comprehensive guidelines for function definitions, API design, database limits, and advanced Convex features.
Sstobo/convex-skills
betterauth-tanstack-convex
Step-by-step guide for setting up Better Auth authentication with Convex and TanStack Start. This skill should be used when configuring authentication in a Convex + TanStack Start project, troubleshooting auth issues, or implementing sign up/sign in/sign out flows. Covers installation, environment variables, SSR authentication, route handlers, and the expectAuth pattern.
Sstobo/convex-skills
Convex Agents Tools
Enables agents to call external functions, APIs, and database operations through tool definitions. Use this when agents need to fetch data, perform actions, or integrate with external services while maintaining clean separation.
Sstobo/convex-skills
convex-queries
This skill should be used when implementing Convex query functions. It provides comprehensive guidelines for defining, registering, calling, and optimizing queries, including pagination, full text search, and indexing patterns.
Didn't find tool you were looking for?