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
ifstatement to decide the next step, use a dynamic workflow.
Lifecycle¶
- Author the workflow JSON.
- Register it (
POST /api/workflows). - Deploy a workflow executor (
POST /api/deploy-workflow/<deployer_id>). - Execute tasks (
POST <executor_url>/api/execute) — directly, or from an agent through the DSL Manager.