Building with DGI

DGI (Dialog Generative Interface) is the reasoning surface where you describe what you want to happen and Orkestia figures out which workflows to run, in what order, with what inputs. It is the front door to Orkestia's hybrid execution model: AI reasons about intent, then that intent is compiled into a deterministic virtual workflow the engine runs the same way every time.

This guide walks the full loop — goal → plan → review → run → promote — with a worked example. It assumes you already understand workflows and have read the DGI concept page.

The mental model

There are three distinct objects in play. Keeping them separate is the key to using DGI well.

DGI reasons in natural language but emits structure. That structure is a VirtualWorkflow — layers of steps, each step bound to a registered workflow type ({provider}.{service}.{operation}), each argument explicitly sourced. The virtual engine then validates it against the live catalog of installed workflow types and compiles it to engine-ready JSON. Once compiled, there is no AI in the execution path — it is a deterministic DAG.

Step 1 — Express a goal

Talk to DGI the way you would brief a capable platform engineer: state the outcome, the constraints, and the inputs you can provide. DGI does not need you to name workflows — capability discovery is its job — but it works best when the outcome is concrete and bounded.

Good goals are specific about the end state:

Stand up a static-site bucket in our AWS sandbox account, upload an index page,
and put it behind a CDN. The bucket name should come from a parameter so I can
reuse this for other sites.

Weaker goals leave DGI guessing about scope ("set up our website infra") — it will ask clarifying questions, but you will iterate more.

Step 2 — How DGI selects and assembles workflows

Under the hood, DGI does not invent capabilities. It works strictly within the workflows that are actually installed and discoverable in your engine host — the same catalog you can browse via the MCP integration or the workflow types registry.

The assembly process, in order:

1. Discover the catalog. The virtual engine reads get_workflows() / entry points on the installed base-library and business-library packages. There is no hand-maintained list of "known" workflows — the catalog is whatever is importable at compile time.
2. Map intent to capabilities. DGI matches each part of your goal to a registered workflow type. "Put it behind a CDN" resolves to a CloudFront-family workflow if one is installed; if not, DGI tells you rather than fabricating one.
3. Order into layers. Steps that can run concurrently share a layer; steps that depend on a prior step's output land in a later layer. This is the DAG.
4. Wire inputs explicitly. Every step argument declares its source — one of three kinds:

   Source	Meaning	Example
   input	A value supplied when the workflow runs	bucket name parameter
   step	A field from a prior step's output	the bucket created upstream
   static	A hardcoded literal baked into the plan	index.html as the object key

   
   There is no implicit global scope and no runtime string templating — every wire is explicit, which is what makes the plan auditable.

Step 3 — Review and refine the plan

Before anything runs, the VirtualWorkflow passes through three-phase validation. Each phase short-circuits with a typed error, so feedback is precise — both for you and for the DGI refinement loop.

A reference-phase error looks like this — note it is structured data, not a stack trace, so DGI can loop it straight back into reasoning:

{
  "phase": "references",
  "step_id": "s2",
  "workflow_type": "aws.s3.put_bucket_taging",
  "reason": "unknown workflow type; did you mean 'aws.s3.put_bucket_tagging'?"
}

When you review a plan, check three things:

• Coverage — does every part of your goal map to a step? Missing steps mean DGI didn't find a capability or misread intent.
• Wiring — are the step mappings pointing at the right upstream outputs? This is where subtle bugs hide.
• Parameterisation — are the values you want reusable expressed as input, not baked in as static?

Refine by replying in natural language ("the index file should be a parameter too, not hardcoded"). DGI re-emits the plan; the validator re-runs. Iterate until the plan is clean.

Worked example: dialog → plan → compiled composition

The dialog

You:  Create a static-site bucket in our AWS sandbox, tag it for cost tracking,
      and make the bucket name a parameter.

DGI:  I'll assemble two layers:
        1. aws.s3.create_bucket      — takes the bucket name from workflow input
        2. aws.s3.put_bucket_tagging — tags the bucket created in step 1
      The bucket name is parameterised as `bucket_name`. The tag set is a
      literal for now. Want it parameterised too?

You:  That's good for a first version.

The plan DGI emits (VirtualWorkflow)

This is the typed intermediate representation — authored as data, not strings, so shape errors are caught before the catalog validator even runs.

{
  "name": "vw_static_site",
  "layers": [
    {
      "name": "create",
      "steps": [
        {
          "name": "s1",
          "workflow_type": "aws.s3.create_bucket",
          "input_mapping": {
            "name": { "source": "input", "field_name": "bucket_name" }
          }
        }
      ]
    },
    {
      "name": "write",
      "steps": [
        {
          "name": "s2",
          "workflow_type": "aws.s3.put_bucket_tagging",
          "input_mapping": {
            "bucket":  { "source": "step", "step": "s1", "field_name": "bucket_name" },
            "tagging": { "source": "static", "value": { "TagSet": [{ "Key": "env", "Value": "demo" }] } }
          }
        }
      ]
    }
  ]
}

The compiled composition (handed to the engine)

The virtual engine compiles the plan into a plain dict in the engine's DAGWorkflow shape. The engine has no idea this came from AI — there is no runtime marker, no AI in the execution path.

{
  "id": "vw_static_site",
  "layers": [
    { "steps": [ { "id": "s1", "workflow": "aws.s3.create_bucket",
                   "inputs": { "name": {"from": "input.bucket_name"} } } ] },
    { "steps": [ { "id": "s2", "workflow": "aws.s3.put_bucket_tagging",
                   "inputs": {
                     "bucket":  {"from": "step.s1.bucket_name"},
                     "tagging": {"value": { "TagSet": [{ "Key": "env", "Value": "demo" }] }}
                   } } ] }
  ]
}

From here it dispatches like any DAG workflow — running in your cloud account via a runner, with state and telemetry flowing back to Orkestia. Watch it through the MCP (watch_workflow) or in Lumen.

Step 4 — Promote a good plan into a reusable virtual workflow

A plan that works is an asset. Rather than re-deriving it through dialog each time, promote it: the compiled composition becomes a named, parameterised virtual workflow that anyone in your org can start directly — no AI round-trip, no per-run reasoning cost.

What promotion buys you:

The promotion path, conceptually:

1. Confirm the plan is clean — passes all three validation phases and produces the composition you want.
2. Name and parameterise it — decide which values stay input (the reusable knobs) and which are static (fixed for this composition).
3. Register the composition as a virtual workflow so it appears in your catalog. See the virtual workflows guide for the authoring details.
4. Run it directly going forward — via the engine API, the MCP integration (start_workflow), or wherever you orchestrate runs.

This is the core of the hybrid execution model: use AI to discover and design a flow once, then run a deterministic composition forever. DGI for the unknown; compiled compositions for the known.

Notes and current limitations

Known limitations to design around:

• Catalog is snapshot-at-compile. DGI assembles against whatever workflow libraries are installed in the calling process at compile time. A workflow type added after a plan is compiled won't appear in that plan; one removed after compile will still be in the JSON and will fail at engine dispatch. Mitigation: keep author-side and runtime library versions pinned and aligned.
• DGI only assembles what exists. It cannot invent capabilities. If your goal needs something not in the catalog, you'll get a references-phase error, not a partial result. Author the missing workflow first (see getting started).
• Out-of-process catalog divergence. If the producer and the compiler run in different environments with different installed libraries, validation can pass against one catalog and fail against the other. Mitigation: compile in the same process that will dispatch, or treat the compiler as a gate service.
• Model variance on the design path. AI reasoning can phrase a plan more than one way; refinement and the three-phase validator are your guardrails. The execution path stays deterministic regardless — variance lives only in design, never in run.
• Naming is still settling. The DGI / Agents / Staff surfaces are converging; some workflow type names (dgi.*) and product boundaries may be renamed before GA.

Where to go next

For per-workflow detail — exact types, inputs, and output fields — see the external catalog at reference.orkestia.dev.