> Source: https://builder.ema.ai/v2/builder-guides/build-your-first-workflow
> Title: Build Your First Workflow

# Build Your First Workflow

A workflow is the directed acyclic graph (DAG) of typed nodes that defines what an AI Employee (AIE) does. This guide walks through building one end to end in the AI Employee builder — defining the inputs it accepts, adding an agent that does the work, wiring the nodes together, passing data between them, testing, and publishing.

By the end you'll have a working single-agent workflow you can run, plus the patterns you need to grow it into something larger.

> [INFO]
> **Prerequisites.** You need a builder role (builder, builder admin, system admin, or env admin) to create and edit workflows. If you can't see the workflows or AI Employees area, ask your administrator for access.

## What you're building

A workflow always starts from a **Start** node and is made of:

-   **Start** — declares the workflow's input fields and (optionally) a schedule.
-   **Agent** nodes — the reasoning steps. Each is one of the configurable agent types.
-   **Transform** nodes — optional deterministic reshapes that don't call an LLM.
-   **Publish** nodes — declare the output fields the workflow exposes.
-   **End** — terminates a branch.

Nodes are joined by **edges**. Data flows along edges, and each agent declares an **input mapping** that pulls specific fields from the Start node or from upstream agents using `{{...}}` references.

For this guide, build a "Ticket triage" workflow: it accepts a support message, classifies its urgency, and writes a short summary.

## Step 1 — create the workflow

1.  Open the AI Employees area and create a new AI Employee (or open the workflows list and create a new workflow). A new workflow opens in the AI Employee builder with a **Start** node and an **End** node already placed.
2.  Give it a name. The name is editable later and is snapshotted onto every run.

The AI Employee builder has an editing surface in the center, an **agent library** on the left, and a configuration panel that slides in from the right when you select a node.

## Step 2 — define the inputs on the Start node

The Start node defines the **input schema** — the typed fields your workflow accepts at run time.

1.  Select the **Start** node to open the **Configure Start Node** panel.
2.  Under **Input Schema**, choose **Add Field**.
3.  For each field, set:
    -   **Key** — the machine name you'll reference later (for example, `message`). Keys must be unique; a duplicate key is flagged inline and blocks saving.
    -   **Type** — one of **Text** (`string`), **Number**, **Integer**, **Boolean**, or **File**.
    -   **Display Title** — the human-readable label shown on run forms (for example, "Customer message").
    -   **Required** — whether a run must supply the field.
4.  Choose **Save Schema**.

For the triage workflow, add one required Text field with key `message` and title "Customer message".

> [TIP]
> The Start node is also where you set a **schedule** so the workflow runs automatically on a recurring cron expression. Scheduling requires a published version, because scheduled runs always execute the latest published version. See [Core concepts](/builder/v2/core-concepts) for how versioning works.

## Step 3 — add an agent

Agents are the reasoning nodes. Ema ships a library of agents built on a small set of base types — including intent classification, search and respond, extraction, rule validation, and a general-purpose custom agent.

1.  In the agent library on the left, find the agent you want. For triage, start with **Intent classifier** (base type `intent_classification`) to label urgency.
2.  Add it to the workflow. A new **agent** node appears with a generated id such as `agent_1`.
3.  Select the node to open its configuration panel on the right.

The panel's exact fields depend on the agent type. Common fields include:

-   **Instructions** — what you want the agent to do, in plain language. See [Writing effective Instructions](/builder/v2/builder-guides/writing-instructions).
-   **Input mapping** — which upstream values the agent receives (next step).
-   Type-specific configuration — for an intent classifier, the **intents** (labels) it can return; for an extraction agent, the **output schema**; for a rule validator, the **rules**.
-   Advanced settings — system prompt, model configuration, execution limits, **Knowledge base**, **Tools**, and human-in-the-loop.

## Step 4 — connect the nodes

Edges define the order of execution and the conditions under which a branch runs.

1.  Drag from the **Start** node's output handle to the agent's input handle.
2.  Drag from the agent to the **End** node (or to a Publish node — see step 6).

The builder blocks invalid connections as you drag: self-loops, duplicate edges, cycles, edges into the Start node, and edges out of the End or Publish nodes are all rejected, and invalid targets are dimmed.

### Conditional edges

To branch on a value, give an edge a **condition**. Select an edge to open its condition editor. A condition compares a resolved field with an operator and a value — for example, route to an "escalate" branch when `output.urgency` equals `high`. Edge conditions reference the source node's output under the `output.*` namespace.

Conditions come in three shapes:

-   **Field** — compare one resolved field value against an operator (equals, greater than, contains, exists, and more).
-   **Fixed** — a constant boolean; this is the default unconditional edge.
-   **Group** — combine several conditions with `all` (AND) or `any` (OR).

When an agent's branching is driven by an intent classifier, dragging from a per-intent handle automatically stamps the matching `output.intent` condition onto the new edge.

## Step 5 — map the agent's inputs

An agent only sees the data you map into it. The **input mapping** editor (in the agent panel) builds `{{...}}` references for you.

1.  In the agent panel, find **Input mapping** and choose **Add**.
2.  Set the **Input name** — the key the agent reads (for example, `instructions`).
3.  Pick the **Source node**:
    -   **Workflow inputs** — a field from the Start node.
    -   An upstream agent — a field from that agent's output.
4.  Pick the **Source field**. For an upstream agent you can also choose **All** to pass its whole output.

Each completed row is serialized to a template reference:

-   A Start-node field becomes `{{workflow_input.<field>}}`.
-   An upstream agent's field becomes `{{<node_id>.output.<field>}}`.
-   An upstream agent's whole output becomes `{{<node_id>.output}}`.

For triage, map the classifier's `instructions` input to the workflow input `message` → the editor writes `{{workflow_input.message}}`.

> [WARNING]
> Some keys are reserved because the agent panel sources them from a dedicated control. For example, an agent that has an **Instructions** textarea reserves the `instructions` mapping key — a mapping row using a reserved key is flagged and is not saved, because it would silently shadow the panel's value at run time. If you set the Instructions field, you don't also need an `instructions` mapping row.

Mark a row **Optional** if the agent should still run when the source value is missing. By default a mapped input is required.

## Step 6 — declare outputs with a Publish node (optional)

A **Publish** node declares the fields your workflow exposes as its public output. Dashboard columns and CSV export are derived from publish-node output fields, so add one if you're building a dashboard AI Employee or want a stable output contract.

1.  Add a **Publish** node from the agent library.
2.  Connect your agent to it.
3.  In the publish-node panel, define the output fields and connect each upstream value to the field it should populate.

A workflow with zero publish nodes simply exposes no output columns — that's a valid choice for chat-style workflows where the response goes straight back to the user.

## Step 7 — save, test, and publish

The builder distinguishes three states:

-   **Save** writes the current DAG as a draft version. Every save with a changed DAG creates an immutable draft version (not yet live). The structure is validated on every save — size limits, required fields, unique node ids, valid edge references, and cycle detection — so errors surface immediately.
-   **Test** runs the workflow against your draft so you can confirm behavior before publishing. Use it to iterate quickly.
-   **Publish** validates the workflow again, captures its configuration, and promotes the version to live. Real runs (API, schedule, and channels) execute the active published version.

To test:

1.  Choose **Save** to persist your draft (the Publish button is disabled while you have unsaved changes).
2.  Choose **Test** and provide values for the input fields you defined. The run streams its progress back to you step by step.

To publish, choose **Publish** and confirm. Publishing is blocked if validation fails — for example, a missing LLM provider, an invalid human-in-the-loop assignee, or a structurally invalid graph.

> [INFO]
> **Draft vs. live.** Saving never changes what's live. Only publishing promotes a version. The builder shows whether your current draft is live (the active version equals the latest) or whether you have unpublished changes (active version is behind the latest).

## How a run executes

When the workflow runs, the engine:

1.  Topologically sorts the DAG and runs nodes in dependency order, executing independent branches in parallel.
2.  Resolves each agent's input mapping by substituting `{{...}}` references with concrete values from the Start input and upstream outputs.
3.  Calls each agent, evaluating outgoing edge conditions to decide which branches continue.
4.  Records a per-step trace — inputs, outputs, status, and token usage — that you can inspect in the run history.

A failed step fails the run (there are no automatic step retries). If an agent pauses for human input, the run pauses and resumes once the person responds — see [Designing human-in-the-loop forms](/builder/v2/builder-guides/designing-hitl-forms).

## Reference

Node type

id prefix

Purpose

`start`

—

Defines the input schema and optional schedule. One per workflow.

`agent`

`agent_`

A reasoning step configured from an agent type.

`transform`

`transform_`

Deterministic, non-LLM field reshaping (no LLM billing, no HITL).

`publish`

`publish_`

Declares exposed output fields for dashboards and CSV export.

`end`

—

Terminates a branch.

Mapping form

Wire reference

Meaning

Workflow input field

`{{workflow_input.message}}`

A field from the Start node.

Upstream field

`{{agent_1.output.urgency}}`

A top-level field from an upstream agent's output.

Upstream "All"

`{{agent_1.output}}`

The whole output of an upstream agent.

> [TIP]
> Workflows have built-in limits to bound execution: a maximum of 50 nodes and 200 edges, enforced at both save and publish. If you hit them, split the work across multiple AI Employees.

## What's next

-   [Writing effective Instructions](/builder/v2/builder-guides/writing-instructions) — make each agent reliable.
-   [Setting up a knowledge base](/builder/v2/builder-guides/knowledge-base-setup) — give agents searched context.
-   [Designing human-in-the-loop forms](/builder/v2/builder-guides/designing-hitl-forms) — pause for human input mid-run.
-   [Autopilot](/builder/v2/autopilot) — build and edit workflows by describing what you want.