AI Workflow Generation

This guide covers Hyphen's advanced prompt-to-workflow drafting flow.

Beta recommendation for API-only tenants

If you want the simplest supported public API path, start with POST /process-studio/processes/create-from-prompt.

That one-shot Process Studio v4 endpoint creates the process, compiles the prompt, and publishes by default. The rest of this guide covers the lower-level draft-generation flow for teams that want raw workflow DSL and explicit control over compose/publish.

It is best used when you want to:

  • bootstrap a first draft quickly
  • work close to the runtime and workflow artifact layer
  • generate a spec, review it, and then provision it deliberately

If you want a more guided authoring experience, start with Process Studio.

What this path produces

A generation request can produce:

  • a workflow definition
  • actions to register
  • custom tables to create
  • external dependency notes, when the draft needs surrounding configuration

The output is powerful, but it still benefits from review before you provision it.

Step 1: Submit a generation request

Describe what you want the workflow to do in plain language:

bash
curl -X POST https://your-hyphen.example.com/ai/generate-workflow   -H "X-Org-Id: acme-corp"   -H "Content-Type: application/json"   -d '{
    "prompt": "Create a workflow that processes incoming invoices. For each invoice, match it against our payment records using PO number and vendor ID. If a match is found within a $50 tolerance, auto-reconcile it. If no match is found, have an AI agent investigate the exception by looking up the purchase order and checking payment history. For invoices over $10,000 that the agent cannot resolve, require manager approval before writing off. Log everything to an audit table.",
    "llmOptions": {
      "model": "gpt-4o",
      "temperature": 0.7
    }
  }'

Response:

json
{
  "generation_id": "llm_gen-123e4567-e89b-12d3-a456-426614174000",
  "status": "processing",
  "message": "Workflow generation initiated. Please use the status endpoint to track progress."
}

Step 2: Poll generation status

bash
curl https://your-hyphen.example.com/ai/generate-workflow/llm_gen-123e4567-e89b-12d3-a456-426614174000/status   -H "X-Org-Id: acme-corp"

Step 3: Retrieve the generated draft

bash
curl https://your-hyphen.example.com/ai/generate-workflow/llm_gen-123e4567-e89b-12d3-a456-426614174000   -H "X-Org-Id: acme-corp"

The response includes the generated workflow and any supporting artifacts the generator produced.

What to review before provisioning

Treat the output as a draft, not something you should publish blindly.

Review:

  • the step sequence
  • branching conditions
  • matcher configuration
  • agent objectives and tools
  • action references
  • context paths
  • custom table assumptions
  • external dependencies that still need real configuration

Step 4: Materialize the draft through Process Studio v4

The supported materialization path for generated DSL is Process Studio v4. After you review the generated package, create a Process Studio project and process, compose the DSL into a bundle, and publish it.

bash
# Create a project once
curl -X POST https://your-hyphen.example.com/process-studio/projects \
  -H "X-Org-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Tenant Workflow Project",
    "description": "Project for generated workflow publication"
  }'

# Create the process definition
curl -X POST https://your-hyphen.example.com/process-studio/processes \
  -H "X-Org-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_123",
    "name": "Invoice Matching Workflow",
    "description": "Generated from AI workflow drafting",
    "authoring_mode": "process_first"
  }'

# Compose the returned DSL package into a bundle
curl -X POST https://your-hyphen.example.com/process-studio/processes/proc_123/compose-from-workflow-dsl \
  -H "X-Org-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_shape": "process_first",
    "summary": "Invoice matching with exception handling",
    "dsl": {
      "hyphen_workflow_definition": { ... },
      "actions_to_register": [ ... ],
      "custom_tables_to_create": [ ... ],
      "workflow_description": "Invoice matching with exception handling"
    }
  }'

# Publish the bundle
curl -X POST https://your-hyphen.example.com/process-studio/bundles/bundle_123/publish \
  -H "X-Org-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "publish_note": "Initial generated workflow publish"
  }'

POST /workflows/create-from-ai is a legacy compatibility path. It is not recommended for new integrations and may be unavailable on some deployments.

Step 5: Execute the published process

bash
curl -X POST https://your-hyphen.example.com/process-studio/processes/proc_123/execute \
  -H "X-Org-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "invoice_batch_id": "batch_123"
    }
  }'

The publish response includes the process execute path, so API-only clients do not have to derive it themselves.

Important caveat

Generated actions may still need configuration before they are ready for production use.

For example:

  • URLs may need to be filled in
  • headers may need secrets
  • database queries may need refinement
  • descriptions may need cleanup

The generator gets you to a draft faster. It does not remove the need for review.

Prompting tips

Better prompts usually include:

  • the business record or object being processed
  • the fields to match or compare
  • thresholds and confidence rules
  • what the agent should investigate
  • when a human should step in
  • whether the workflow is scheduled

Example: weak prompt

Create a workflow to process invoices

Example: stronger prompt

Create a workflow that matches incoming invoices to payment records on PO number and vendor ID with a $50 amount tolerance and a 5-day date window. Use fuzzy matching on vendor names at 85% threshold. For unmatched invoices, have an AI agent investigate by looking up the PO in our ERP, checking payment history, and searching for duplicates. If the agent's confidence is below 0.8, pause for human review. Log the results to a reconciliation_audit table. Run daily at 6 AM Eastern.

For most teams, a good pattern is:

  1. generate a draft from a business description
  2. review and refine the output
  3. provision deliberately
  4. iterate once the workflow shape is clearer

If you want a product surface that structures that process more tightly, use Process Studio.