AI Employees
An AI Employee 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.
A Chat, Dashboard, or Voice AI Employee is a workflow. There is no separate "AI Employee" record behind the scenes; the 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. An Orchestrator AI Employee is the exception: it has no workflow and is configured on its Configuration tab instead. See Orchestrator AI Employees.
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.
The stages below describe Chat, Dashboard, and Voice AI Employees. An Orchestrator AI Employee follows the same create, configure, publish, and monitor path, but its configure step is a settings page rather than a workflow editor. See Orchestrator AI Employees.
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 workspace.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 AI Employee 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 (Beta) | 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 scheduled trigger, 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 workspace.
Roles and access
Two layers of access apply to an AI Employee.
Workspace 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 workspace.
- A non-empty list restricts access to its members (plus the creator, who always has access, plus workspace admins).
Authors can share their own AI Employee with a group directly from the Permissions tab.
A workspace user who holds a per-AI-Employee Admin grant can access the Knowledge Bases and Tags configuration sections for that AI Employee, in addition to the standard builder-role access those sections have always required.
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.
Bulk-inviting users via CSV
From the Permissions tab of an AI Employee, builders with the manage-grants tier can bulk-invite workspace members by uploading a CSV file. The upload flow lets you choose a role for everyone in the file before you upload it. The role applies to the whole file; you select it from a picker that appears above the drop zone.
After the file is processed (first as a dry run, then on confirmation), the review table shows a per-row outcome:
| Outcome | Meaning |
|---|---|
| Added | The user was granted access with the chosen role. |
| Already has a role - not changed | The user already held a role on this AI Employee; nothing changed. |
| Added, but the role did not apply | The user was admitted, but the role assignment was refused. Re-uploading repairs it. |
| Invite not accepted yet | The user's workspace invite is still pending; a user admin must resend it. |
| Account is deactivated | The account is deactivated; a user admin must reactivate it. |
| Not a workspace member | The email address is not a member of this workspace. |
| Could not be read | The row could not be processed. |
Each row in the review table also shows the role that was conferred and where it came from: From file when the CSV's own role column provided it, or From selection when the file's role column was blank and the picker's value was used instead.
The AI Employees list: archived-only state
When every AI Employee visible to you is archived, the AI Employees page shows a No active AI Employees message with a Show archive button instead of a blank page. Clicking Show archive switches the list to the archive view so you can restore an AI Employee or review what was archived.
Categories
When you create or edit an AI Employee, you can assign it a category. Categories are labels used to group and filter AI Employees on the AI Employees page. The category field appears in the AI Employee creation dialog and in the Edit AI Employee dialog.
Where to go next
- Workflows: the DAG that defines an AI Employee's behavior.
- Agents: the reasoning nodes you configure inside the workflow.
- Orchestrator AI Employees: the interaction type that coordinates other AI Employees instead of running a workflow.
- Builder guides: hands-on instructions for building each part.