Flows

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

Flows are Orqestra’s orchestration primitive. A flow is a governed orchestration_flow asset whose content describes how a workload receives an input, executes steps, branches, calls models and tools, and returns output.

What A Flow Contains

Every flow definition includes:

Flows are authored as JSON or YAML. The control plane compiles that source once into a deterministic intermediate representation (IR), then stores the source, IR, diagnostics, compiler versions, and hashes together in a versioned WorkflowArtifactEnvelopeV1. The envelope is the immutable content of the AssetVersion; its checksum is also the object-store artifact integrity check. Accepted releases bind an exact asset version and checksum, so runtime and release readers retrieve and verify the stored artifact rather than recompiling or substituting the latest version.

Trigger Types

The current public flow schema supports these trigger types:

Example:

{
  "type": "api_request",
  "inputs_schema": {
    "type": "object",
    "required": ["question"],
    "properties": {
      "question": { "type": "string" }
    }
  }
}

Step Types

The current public schema supports these step types:

Runtime References

Bindings and step payloads resolve against these runtime scopes:

The current runtime resolves trigger, flow.inputs, steps, ctx, and release references. Older examples that use trigger.inputs.* or context.* are not the current contract.

Observability Fields

The current flow schema supports these top-level observability settings:

Individual steps can also declare trace, trace_content, metrics, context_read, context_write, and output_schema.

For provider-backed steps, inputs.max_tokens is the step-local completion budget. Use it when one flow needs different output sizes for different model or agent steps. If it is omitted, runtime falls back to the release-bound model_policy.max_tokens, then model_policy.max_completion_tokens_default.

Example Flow

This example uses governed retrieval plus a direct LLM call:

name: Knowledge Assistant Flow
description: Evaluate policy, retrieve context, and answer a user question.
 
trigger:
  type: api_request
  inputs_schema:
    type: object
    required: [question]
    properties:
      question:
        type: string
 
observability:
  trace_all: true
  metrics: [latency, token_count, cost]
 
entry_step: retrieve
 
steps:
  - id: retrieve
    type: task
    action: retrieve_documents
    inputs:
      question: "{{trigger.question}}"
      knowledge_base_ref: "{{release.knowledge_base}}"
    next: answer
 
  - id: answer
    type: llm_call
    inputs:
      messages:
        - role: user
          content: "Answer the question using the retrieved context: {{trigger.question}}"
    next: respond
 
  - id: respond
    type: return
    output:
      answer: "{{steps.answer.output.content}}"
      sources: "{{steps.retrieve.output}}"

Validation Rules

The server compiler is the semantic authority and enforces two layers of validation:

1. Source-schema validation against orchestration_flow.schema.json and the versioned source contract
2. Structural and semantic compilation for graph integrity and the full IR

That means the platform checks:

• entry_step references a real step ID
• transition fields such as next, on_success, on_failure, on_timeout, parallel_steps, join_from, loop_steps, and cases resolve correctly
• step IDs are unique
• all steps are reachable from the entry point
• agent_handoff steps define either agent_ref or agent_selector

You can validate a candidate flow without creating a new version:

curl -X POST http://localhost:8000/v1/flows/{flow_id}/validate \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "name": "Candidate Flow",
      "description": "Example",
      "trigger": { "type": "manual" },
      "entry_step": "done",
      "steps": [
        {
          "id": "done",
          "type": "return",
          "output": { "status": "ok" }
        }
      ]
    }
}'

The response includes stable diagnostics and source/IR identities. To retrieve the lossless stored artifact for an existing version, use:

orqestractl flow artifact {flow_id} {asset_version_id} --workspace {workspace_id}

This artifact route is read-only evidence: it returns the verified canonical source and full IR from the selected version, not caller-provided content.

orqestractl flow validate --file flow.yaml is an offline structural check. It is useful for quick feedback, but its result is explicitly non-authoritative and does not mean the flow is ready for release. Supply --flow-id (and, when needed, --workspace) to call the server-authoritative /v1/flows/{flow_id}/validate endpoint. Creation and versioning always use the server compiler and persist an envelope; compiler-invalid fields are rejected before a version or artifact is published.

Authoring Guidance

Use task for plugin-driven work, llm_call for direct model interaction, and agent only when you need a goal-driven reasoning loop. Keep return values explicit and bind release roles consistently (model_policy, prompt_template, policy_bundle, knowledge_base, orchestration_flow, and similar roles). Retrieval controls are part of the bound knowledge_base content, not a separate release binding.

If you are writing flows in YAML, validate them before creating a release. The most common drift issues are stale step types, stale trigger shapes, and old binding expressions.