Workflows and Actions

A workflow is the executable program that defines an AI Employee's behavior. A workflow is composed of actions -- discrete units of work that the engine executes in sequence according to a directed acyclic graph (DAG).

Action Types

An ActionType is analogous to a function signature. Each action type defines:

• A unique name identifying the action.
• Input parameters -- the data the action consumes, each with a name and type.
• Output parameters -- the data the action produces.
• An implementation type that tells the engine how to invoke the action (e.g., via RPC to a backend service).

Ema provides a large library of pre-built action types (agents) covering common tasks. Builders select from this library when constructing workflows -- action registration is managed internally by the platform.

• Search agents -- Retrieve information from knowledge bases, web, or connected applications.
• LLM agents -- Generate text, classify content, extract entities, or respond to queries.
• Classification & Routing agents -- Categorize incoming requests and route them to the appropriate workflow branch.
• Response agents -- Publish or deliver the final output of a workflow to the end user or downstream system.
• Tool agents -- Execute external API calls, database queries, or other integrations.
• Human Collaboration agents -- Pause execution for human review, approval, or input (Human-in-the-Loop).
• Validation agents -- Apply rule sets and business logic checks.
• Conversion agents -- Transform data between formats (e.g., Convert to Text).
• Custom Code agents -- Execute sandboxed JavaScript or TypeScript code within workflows for bespoke processing logic that falls outside standard agent capabilities. The sandbox does not support third-party packages or other languages.

Action Instances

An ActionInstance is a single invocation of an action type within a workflow -- analogous to a single line of code that calls a function. Each action instance specifies:

• Which action type to call.
• Bindings that connect each input parameter to a data source.
• An optional run-if condition for conditional execution (see Conditionals).

WorkflowDef
+-- Action Instance: "search_knowledge_base"
| +-- Type: search/v2
| +-- Input: query <- workflow_input("user_message")
| +-- Output: search_results
+-- Action Instance: "generate_response"
| +-- Type: call_llm
| +-- Input: context <- search_knowledge_base.search_results
| +-- Output: response_text
+-- Workflow Output: "response" <- generate_response.response_text

The DAG Model

The engine compiles a workflow definition into a DAG by inspecting the set of action instances and their bindings:

1. Nodes are action instances.
2. Edges are bindings -- each edge represents a data dependency from one action's output to another's input.
3. Topological ordering ensures that every action runs only after all of its dependencies have completed.

Parallel Execution

Actions that have no data dependencies between them can execute in parallel. In the following example:

Trigger --> A --> B
 \-> C
 B, C --> D

Actions B and C both depend only on A, so they run in parallel after A completes. Action D waits for both B and C before executing.

Cycle Detection

The engine rejects workflow definitions that contain cycles. A cycle means an action depends (directly or transitively) on its own output, which would create an infinite loop.

Workflow Definition Structure

A workflow is defined as a WorkflowDef protobuf message containing:

Execution Flow

When a workflow is invoked:

1. Input assembly: The engine receives the invocation request (e.g., a user message) and maps it to workflow inputs.
2. Graph traversal: The engine walks the DAG in topological order.
3. Action execution: For each action instance:
   • Assemble input data from upstream outputs, workflow inputs, constants, or persona widgets.
   • Evaluate the run-if condition (if present). Skip the action if the condition is false.
   • Invoke the action provider (typically via RPC).
   • Store the output for downstream consumers.
4. Output collection: Once all actions have completed (or been skipped), the engine collects the configured workflow outputs and returns them.

Not every invocation is guaranteed to return all configured outputs. Conditional branches may cause some actions (and their outputs) to be skipped. See Conditionals for details.

Action Providers

The workflow engine itself does not implement individual action logic. Instead, it delegates to action providers -- remote services that host the actual code for each action. The engine is responsible for:

• Orchestrating the order of execution and data flow.
• Mediating data between actions (type-checking, binding resolution).
• Handling conditional logic and skip propagation.

The actual reasoning, search, or API call logic lives in the action provider services.

Next: Conditionals