AI Employees
An AI Employee (AIE) is the top-level thing you build, configure, version, and deploy on Ema. It bundles one workflow together with the agents, knowledge bases, and Tools that workflow uses, plus the configuration that controls how end users reach it. When you create an AI Employee you are creating a workflow; when you deploy an AI Employee you are publishing that workflow.
An AI Employee is a workflow. There is no separate "AI Employee" record behind the scenes — an AI Employee and its workflow share one identity. Anywhere the API exposes an ai_employee_id, it is the same UUID as the underlying workflow_id. Knowledge bases, dashboard tables, and generated documents are all scoped to that one ID, so they belong to the AI Employee across every run.
What an AI Employee owns
A single AI Employee is the owner of everything you assemble for it:
| Resource | What it is | Learn more |
|---|---|---|
| Workflow | The DAG of typed nodes that defines the AI Employee's behavior. Exactly one per AI Employee. | Workflows |
| Agents | The reasoning nodes inside the workflow. Each is configured from one of a small set of agent types. | Agents |
| Knowledge bases | Private document collections the agents search at run time via RAG. Scoped by ai_employee_id. | Knowledge Bases |
| Tools | Connected integration functions and MCP servers the agents can call. | Integrations and data |
| Versions | An immutable history of the workflow definition, with one live published version at a time. | Workflows |
| Runs | The execution history, with per-step traces and token usage. | Workflows |
Because all of these are scoped to the AI Employee's ID, deleting or restoring an AI Employee carries its resources with it, and access control is enforced once at the AI Employee boundary.
The AI Employee lifecycle
An AI Employee moves through four stages. Each stage maps to concrete screens and actions in the AI Employee builder.
1. Create
Start a new AI Employee from a template or from a blank workflow. Templates seed the workflow DAG, default configuration, and a recommended interaction surface so you can run something immediately and customize from there.
- Open the AI Employees page and start a new AI Employee.
- Pick a template, or start blank.
- The platform creates the workflow in
draftstatus with an initial version.
The interaction surface (how end users reach the AI Employee — see Surfaces) is chosen at create time, because it shapes the trigger node and the default DAG. Creating AI Employees requires a builder-capable role; see Roles and access.
2. Configure
Configuration happens in the AI Employee builder. You will:
- Edit the workflow — add and connect nodes, set conditions on edges, and map data between nodes with
{{variable}}references. - Configure agents — set each agent node's Instructions, LLM behavior, attached knowledge bases, and Tools. See Agents.
- Attach knowledge bases — select the document collections agents should search. See Knowledge Bases.
- Connect Tools — select integration functions and MCP servers an agent may call.
- Declare outputs — publish nodes declare the named outputs the AI Employee produces; these are the AI Employee's public output contract.
Every change to the workflow is saved as a new draft version. Nothing you do here affects what end users see until you publish.
3. Deploy
Deploy by publishing the workflow. Publishing validates the DAG, runs pre-flight checks, snapshots the configuration and attached knowledge bases into an immutable version, and marks that version live. From that moment, new runs execute against the published version.
Pre-flight validation can block a publish. The most common blockers are:
NO_LLM_PROVIDER— an agent node references an LLM provider that isn't enabled for your tenant.HITL_INVALID_ASSIGNEE— a human-in-the-loop node assigns a request to a user who doesn't exist.- A
DAG_INVALID_*code (for exampleDAG_INVALID_NODEorDAG_CYCLE_DETECTED) orDAG_TOO_LARGE— the workflow fails structural validation (see Workflows).
Publishing is covered in depth in Workflows.
4. Monitor
After deployment, observe and improve the AI Employee:
- Runs — review the execution history. Each run carries a per-step trace (input, output, status, tokens, and the condition results on each outgoing edge). See Workflows.
- Audit — configuration changes, publishes, version promotes and reverts, and access changes are all recorded as audit events. See Administration.
- Versions — compare the live version with earlier ones, and promote or revert if you need to change which version is live. See Workflows.
- Feedback — when enabled, end users can rate individual responses, and the configured positive and negative reasons surface in your analytics.
Surfaces
An AI Employee is one workflow, but end users can reach it through different surfaces. The surface determines the trigger node and the shape of the input the workflow receives; the rest of the DAG is the same.
| Surface | How users reach it | Notes |
|---|---|---|
| Web chat | A conversational workspace in the browser | The default conversational surface. Supports per-response feedback and source citations. |
| Embeddable chat | A widget embedded in another site or channel | Served from the chatbot host; anonymous visitors are supported as external chat visitors. |
| Dashboard | A spreadsheet-style grid of rows | Built for high-volume, repeatable runs (one run per row). Output columns are derived from the workflow's publish-node output fields; supports CSV export. |
| Voice | Real-time telephony or browser calling | Beta. See Voice AI Employee. |
| API | A programmatic call to start a run | Start a run with input_params; read the run and its named outputs back. See API reference. |
| Scheduled / triggered | A cron schedule, or a document finishing ingestion in an attached knowledge base | Each fire starts a run against the live published version. |
Beta. The Voice AI Employee surface and the Recruiter AI Employee are beta features. Availability is enabled per tenant.
Roles and access
Two layers of access apply to an AI Employee.
Tenant role governs what you can do platform-wide. Creating and editing AI Employees requires a builder-capable role — builder, builder_admin, system_admin, or env_admin. The user role can use an AI Employee but cannot build or configure it.
Per-AI-Employee access governs who can act as a specific AI Employee. Each AI Employee has an access list:
- An empty access list means the AI Employee is open to everyone in the tenant.
- A non-empty list restricts access to its members (plus the creator, who always has access, plus tenant admins).
This membership rule is the single source of truth for "is this user allowed to act as this AI Employee," and it is reused by the knowledge base and search services when they scope data by ai_employee_id — so a change to the rule applies everywhere consistently.
Where to go next
- Workflows — the DAG that defines an AI Employee's behavior.
- Agents — the reasoning nodes you configure inside the workflow.
- Builder guides — hands-on instructions for building each part.