output-dev-workflow-function

Creating workflow.ts Files

Overview

This skill documents how to create workflow.ts files for Output SDK workflows. The workflow file contains the main orchestration logic that coordinates step execution.

When to Use This Skill

• Creating a new workflow's main definition
• Understanding workflow structure requirements
• Debugging workflow orchestration issues
• Refactoring existing workflow logic

Critical Rules

1. Import Pattern

// CORRECT - Import from @outputai/core
import { workflow, z } from '@outputai/core';

// WRONG - Never import z from zod
import { z } from 'zod';

2. ES Module Imports

All imports MUST use .js extension:

// CORRECT
import { stepName } from './steps.js';
import { WorkflowInputSchema } from './types.js';

// WRONG - Missing .js extension
import { stepName } from './steps';
import { WorkflowInputSchema } from './types';

3. Determinism Requirement

CRITICAL: The workflow fn must be deterministic. No direct I/O operations are allowed in the workflow function.

// WRONG - Direct I/O in workflow
export default workflow( {
  // ...
  fn: async input => {
    const response = await fetch( 'https://api.example.com' ); // NEVER do this!
    return response.json();
  }
} );

// CORRECT - Delegate I/O to steps
export default workflow( {
  // ...
  fn: async input => {
    const result = await fetchDataStep( input ); // Steps handle I/O
    return result;
  }
} );

Related Skill: output-error-nondeterminism

Basic Structure

import { workflow, z } from '@outputai/core';

import { stepOne, stepTwo } from './steps.js';
import { WorkflowInputSchema, WorkflowOutput } from './types.js';

export default workflow( {
  name: 'workflowName',
  description: 'Brief description of what the workflow does',
  inputSchema: WorkflowInputSchema,
  outputSchema: z.object( { /* output shape */ } ),
  fn: async ( input ): Promise<WorkflowOutput> => {
    // Orchestrate step calls
    const result = await stepOne( input );
    const final = await stepTwo( result );
    return final;
  }
} );