AI Flow Generation

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Orqestra can draft flow definitions from natural-language descriptions. Describe the intended behavior and explicitly name any existing assets needed as context. Review and validate the generated flow before using it; generation does not automatically inspect the workspace asset inventory.

How It Works

The flow generator takes a plain-English description and produces a structured flow definition:

1. You describe the desired workflow behavior
2. The generator uses the platform vocabulary and the context you provide; name existing assets explicitly when they are needed
3. It produces flow YAML for you to validate, review, and refine
4. You review, refine, and deploy

The generated flow follows the same schema as hand-authored flows and can be edited in the visual flow editor or YAML.

Using the API

curl -X POST /v1/flows/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "workspace_id=$WORKSPACE_ID" \
  -d '{
    "description": "Classify incoming support tickets by urgency (low/medium/high), send high-urgency tickets to Slack, and store all results in PostgreSQL"
  }'

Response:

{
  "flow_content": {
    "name": "Support Ticket Classifier",
    "description": "Classifies tickets by urgency and routes high-priority ones to Slack",
    "trigger": { "type": "api_request" },
    "entry_step": "classify",
    "steps": [
      {
        "id": "classify",
        "type": "llm_call",
        "config": {
          "model_config_ref": "gpt4-standard",
          "prompt": "Classify this support ticket as low, medium, or high urgency: {{ inputs.ticket_text }}"
        },
        "next": "route"
      },
      {
        "id": "route",
        "type": "condition",
        "condition": "{{ steps.classify.output.urgency == 'high' }}",
        "branches": [{ "when": "true", "then": "notify_slack" }],
        "next": "store_result"
      },
      {
        "id": "notify_slack",
        "type": "task",
        "config": {
          "plugin": "slack_message",
          "channel": "#support-urgent",
          "message": "High-urgency ticket: {{ inputs.ticket_text }}"
        },
        "next": "store_result"
      },
      {
        "id": "store_result",
        "type": "task",
        "config": {
          "plugin": "postgres_query",
          "query": "INSERT INTO ticket_classifications ..."
        }
      }
    ]
  },
  "warnings": [],
  "generation_id": "9f43b1d1-2f7e-4d64-8b78-0f3b91a4f6f8"
}

Using the CLI

# Generate and save
orqestractl flow generate \
  --description "Summarize uploaded documents and email the summary to the team every Monday" \
  --output generated-flow.yaml
 
# Validate the generated flow
orqestractl flow validate --file generated-flow.yaml
 
# Create it
orqestractl flow create --slug weekly-summary --owner team:ops --file generated-flow.yaml

Using the Portal

In the visual flow editor, click Generate with AI and type your description. The generated flow appears on the canvas where you can refine it visually before saving.

The API resolves the built-in generator workload and its active production release on the server. The generator runs under its own system credential, provisioned automatically at startup — you do not need a principal binding of your own on the generator workload. Authorization is decided against the target workspace instead. The API requires an inline governed-runtime result, parses the nested result envelope, validates the generated YAML, and returns no partial draft on failure. Expect 403 when you lack asset-create permission on the target workspace or on policy denial, 503 when the generator has no active release or has not been fully provisioned, and 409 inline_dispatch_unavailable when the runtime cannot provide synchronous results.

Conversational Refinement

The generator supports iterative refinement. After the initial generation, you can provide follow-up instructions:

curl -X POST /v1/flows/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "workspace_id=$WORKSPACE_ID" \
  -d '{
    "description": "Add a policy evaluation task before the LLM call to screen for PII risk, and add error handling that retries failed steps up to 3 times",
    "refinement_context": [{ "note": "Preserve the current output fields" }],
    "current_flow": "name: support-ticket-classifier\nentry_step: classify\nsteps: [...]"
  }'

What the Generator Knows

Workspace authorization governs who may generate, but the current prompt does not automatically inject the workspace asset inventory. It is grounded in the platform flow vocabulary and the context you send:

Best Practices

Be specific about data flow. Instead of “process the data”, say “extract the customer name from the email, look up their account in PostgreSQL, and generate a personalized response.”

Mention integrations explicitly. Say “send to Slack” or “store in PostgreSQL” so the generator selects the right plugins.

Review and validate before deploying. Generated flows are valid structurally but may need tuning for your specific data shapes and business logic.

Use the visual editor to refine. Generation gives you a starting point; the flow editor lets you visually adjust connections, add error handlers, and configure step details.