Skip to content

Introduction to Workflows

What Is a Workflow?

A workflow is a description of a process: a set of steps (called nodes) and the rules that decide in which order they run and what data each one receives. In AgentGr.id a workflow can combine three kinds of steps:

Node type What it does
Policy node Deterministic logic: rules, API calls, or long-running jobs
Agent node AI-driven work, performed by an agent through the Delegate API
Workflow node Another workflow, nested as a single step

This mix is what makes workflows agentic: deterministic steps provide reliability and control, while agent steps provide reasoning and flexibility.

What Is the Workflow DSL, and Why Use One?

A DSL (Domain-Specific Language) is a small language designed for one job. The workflow DSL is a JSON format with two parts:

workflow
├── header       ← identity (name, version, release) and metadata
└── body
    ├── nodes    ← the steps
    └── graph    ← how they connect, or who decides at runtime

Describing workflows as data rather than code has practical benefits:

  • Validation before execution — the executor checks the structure before anything runs.
  • Versioning — every workflow is identified as {name}:{version}-{release}, so versions are immutable and can be rolled back.
  • Portability and reuse — workflows are registered once and referenced by URI from agents, other workflows and planners.
  • Readable by machines and LLMs — planners can inspect, select and even generate workflows.

At runtime a workflow is interpreted by the workflow executor, which runs as its own service and coordinates policy executors, the agent Delegate API and nested workflow executors.

The Two Workflow Types

Static workflows Dynamic workflows
Execution order Defined up front as a graph Decided at runtime by a router agent
How it runs Topological order of the graph (fan-out / fan-in supported) Router returns the next batch of nodes after each batch completes
Branching Every node in the graph runs Branches chosen from the content of previous outputs
Loops and retries Not supported Supported — the router can schedule a node again
Predictability High — the same input always follows the same path Lower — the path adapts to the data
Best for Fixed pipelines, ETL-style processing, compliance steps Decision-driven processes, triage, iterative refinement

When to Use Which

Situation Use
Execution order is always the same Static
All branches are always taken (just in a different order) Static
A branch depends on the content of a previous output Dynamic
You need to loop or retry based on results Dynamic
Several steps run but only one branch continues, depending on results Dynamic

Rule of thumb: if you would need an if statement to decide the next step, use a dynamic workflow.

Lifecycle

  1. Author the workflow JSON.
  2. Register it (POST /api/workflows).
  3. Deploy a workflow executor (POST /api/deploy-workflow/<deployer_id>).
  4. Execute tasks (POST <executor_url>/api/execute) — directly, or from an agent through the DSL Manager.

Next