Docs

Documentation

Orchestrate AI behaviour with workflows

Workflows capture provider choices, fallbacks, structured outputs, and cached fields so you can adapt quickly.

What are workflows?

Workflows are the core building blocks of ModelRiver. Each workflow encapsulates a complete AI request configuration: provider, model, fallback strategy, structured output schema, and cache fields: into a reusable, versioned unit.

Instead of hardcoding AI provider logic into your application, you define workflows in the ModelRiver console and reference them by name in your API calls. This separation means you can swap providers, update models, or adjust fallback strategies without deploying code changes.

Key capabilities

  • Provider routing: Choose primary and fallback providers per workflow. ModelRiver automatically retries with backups when the primary fails or times out.
  • Structured outputs: Attach JSON schemas to guarantee the shape of AI responses. ModelRiver validates and merges responses so required fields are always present.
  • Cache fields: Surface business identifiers (user IDs, segments, experiment buckets) in API responses under customer_data without storing full payloads.
  • Test mode: Validate integrations with predictable sample data, zero provider calls, and no quota consumption.
  • Event-driven hooks: Attach event names to trigger webhook callbacks for asynchronous processing between AI generation and final delivery.

When to create multiple workflows

  • Different use cases or product features require distinct prompts or structured outputs.
  • You want to A/B test providers or models: create dedicated workflows for each variant.
  • You serve multiple customer tiers with different fallbacks or cost considerations.

Best practices

  • Keep workflow names human-readable; they appear in API responses and logs.
  • Document the intent of each workflow within your team's runbooks or inside the description field.
  • Monitor fallback frequency: if backups trigger frequently, adjust primary providers or prompts.
  • Use the Workflow Playground before promoting changes to production.

Next steps