Tracking Custom Events
A custom event records something your AI Employee does that the built-in metrics don't capture, such as an invoice approved, a claim paid, or a ticket closed. Each time a published run reaches the step that records it, Ema saves one entry with the values you chose. You then chart those entries on the Metrics tab, the same way you chart workflow runs or tool calls.
Custom events are enabled per Workspace. If you don't see an Events button on an AI Employee's Metrics tab, custom events are not turned on for your Workspace. Ask your Ema contact.
How it works
- Define the event. Give it a name, a description of when it's recorded, and the fields to save with each entry.
- Record it in the workflow. Add an Emit Event Agent and connect each field to a value from an earlier step.
- Publish the AI Employee. Published runs record entries. Test runs in the editor do not.
- Chart it. Add a chart on the Metrics tab and pick the event as its dataset.
Where to find events
Events live in three places, one for each scope an event can belong to.
| Scope | Where | What you see |
|---|---|---|
| AI Employee | Open the AI Employee, select the Metrics tab, then Events. | The events this AI Employee records, both its own and the shared events it uses. |
| Group | Open the Group, select the Metrics tab, then Events. | Events shared with the Group. AI Employees in the Group can use them, and their entries add up in the Group's Metrics. |
| Workspace | Select Metrics in the main navigation, then the Events tab. | Events defined across the Workspace, its Groups, and its AI Employees. |
The Events panel on an AI Employee has two tabs, Events and Calculated fields. This page covers Events.
Create an event
Open the AI Employee's Events panel and select New event. Choose how to start:
- Describe with Autopilot. Autopilot asks whether you want to use an event your Group or Workspace already shares, or build a new one. For a new event it asks what outcome you want to record, proposes the fields, and proposes the step that records it with its fields connected. It shows you the plan before it changes anything, and it does not publish without your approval.
- Add manually. Choose Use a shared event to join an event your Group or Workspace already has (see Use a shared event), or Build your own to define a new one.
Build your own
- Enter an Event name, for example "Invoice processed". Names can be up to 100 characters.
- Enter a Description that says when the event is recorded, for example "When a support ticket is closed."
- Add Fields:
- Select Pick fields from AI Employee outputs to choose outputs that steps in this workflow already produce. The field's type comes from the output.
- Select Add field for a value no step produces yet. You choose or create its source later, when you connect the Emit Event Agent.
- Select Save and add to workflow.
The event is saved to the AI Employee's draft. Next, connect its fields in an Emit Event Agent, then publish the AI Employee. See Record the event in the workflow.
Use IDs, not names or email addresses. Every entry is stored and can be charted and exported. Record an invoice ID or a ticket ID rather than a person's name or email address.
Fields
Each field has a name, a type, an optional description, and a Required setting. Field names must be unique within the event.
| Type | Values | Limit per event |
|---|---|---|
| String | Text. | 15 |
| Number | A finite number. | 15 |
| Boolean | True or false. | 10 |
| Date | A calendar date, written YYYY-MM-DD. | 10, for dates and datetimes combined |
| Datetime | A date and time with a timezone, in RFC 3339 format, for example 2026-11-09T14:30:00Z. |
An event can have up to 50 fields in total. Each field holds a single value: lists and nested objects are not supported.
- Required. Fields are optional by default. If a required field has no value when the step runs, that entry is not recorded.
- Default for earlier events. Under Advanced · Earlier events, you can give a field a default value. Charts use it for entries recorded before the field existed, so adding a field doesn't leave older entries blank.
Record the event in the workflow
Defining an event doesn't record anything on its own. A step in the workflow has to record it.
With an Emit Event Agent
The Emit Event Agent records one entry each time it runs. Find it in the Planning & Resources group of the agent library.
- Open the workflow in the AI Employee builder and add an Emit Event Agent after the step whose outputs hold the values you want to record.
- Under Event, select the event. Only events in this AI Employee's Events panel appear here.
- For each field, connect an output from an earlier step, or choose Constant and enter a fixed value. Optional fields you leave unbound are left out of the entry.
- Save the workflow, then publish the AI Employee.
You don't need fields for which Workspace, AI Employee, or run an entry came from. Ema adds those to every entry automatically.
If you change an event's fields after adding the step, the step shows that the fields changed. Select Reload event schema. Connections to fields that still exist with the same type are kept. Connections to removed or changed fields are cleared, and you need to connect any new required field before you publish.
From a Code Agent script
A Code Agent script can also record an event with the built-in emit_event function. It takes exactly two arguments: the event's alias and an object of field values.
function main(inputs: Inputs) {
for (const invoice of inputs.invoices) {
if (invoice.status === "approved") {
emit_event("Invoice processed", {
invoice_id: invoice.id,
amount: invoice.amount,
status: invoice.status,
});
}
}
return { recorded: inputs.invoices.length };
}
The alias is shown in the event's details on the AI Employee's Events panel. Use it exactly as shown. It stays the same if the event is renamed. Field names that contain spaces must be quoted in your script.
If Ema rejects an entry, for example because a required field is missing or a value has the wrong type, emit_event throws an error. Catch it to keep the script running, or let it fail the step.
Use a script when one run should record several entries, or when the values need logic to work out. Otherwise, the Emit Event Agent is simpler and Ema can check that it's connected.
Publish and check that it's recording
Events are recorded only by published runs. Test runs in the editor and evaluation runs don't record entries: the Emit Event Agent shows the entry it would have recorded instead.
The Status and Next step columns on the AI Employee's Events panel tell you where each event stands.
| Status | What it means | Next step |
|---|---|---|
| Draft | The event was saved but not published. | Open it and select Save and add to workflow again. |
| Not in workflow | No Emit Event Agent records this event yet. | Add an Emit Event Agent and connect its fields. |
| Not published | An Emit Event Agent records it in the draft, but the draft isn't published. | Publish the AI Employee. |
| Recording | Published runs record this event. | Chart it. If a chart is empty, check for recent runs and the chart's date range. |
| Couldn't check | A Code Agent script may record it. Ema can't look inside scripts. | Look for the event in a recent published run. |
Chart an event
- On the Metrics tab, select Edit dashboard, then Add and Chart.
- Open the dataset list. Your events appear under Your events, with their version.
- Pick a chart type and measures, for example a count of entries, and group or filter by the event's fields.
- Save the chart, then publish the dashboard.
Everything in Building a custom metrics view applies to event charts: chart types, filters, drafts, and publishing. On a Group's Metrics tab, a shared event's entries add up across every AI Employee in the Group that records it.
Share events across AI Employees
Sharing lets several AI Employees record the same event, so their numbers add up in Group and Workspace charts.
Share an AI Employee's event with its Group
Open the event on the AI Employee's Events panel and select Share with your Group. Other AI Employees in the Group can then use it. This AI Employee keeps recording it and its history stays. You can't undo a share.
After sharing, the Group's event managers decide future changes to its fields. Edits you haven't published are not shared. If the AI Employee leaves the Group, it can no longer record the event.
To share, you need edit access to the AI Employee and permission to manage the Group's events. The AI Employee must belong to a Group.
Use a shared event
- On the AI Employee's Events panel, select New event, then Add manually and Use a shared event.
- Pick an event. The Matches your outputs column shows whether this AI Employee produces every field the event needs. A match is by field name and type.
- Connect its fields in an Emit Event Agent, then publish.
You can only pick an event when this AI Employee produces all of its fields. A shared event stays up to date when its Group or Workspace changes it.
Create and promote shared events
On a Group's Events panel, select New Group event to define fields every AI Employee in the Group should record. Each AI Employee connects its own values.
You can also promote an existing event to a wider scope: an AI Employee's event from the Group's Events panel, or any Group or AI Employee event from the Workspace Events tab. Promoting makes a shared copy with the same fields. AI Employees that already use the original stay as they are.
See which AI Employees use an event
The Used by column on the Group and Workspace events lists counts the AI Employees that use each event. Select it to see them, with whether each one uses the event in its current draft or its published version. The list shows only AI Employees you have access to.
Change or stop recording an event
- Edit an event. On an AI Employee, your changes are saved to its draft and take effect when you publish it. Published changes reach every AI Employee that uses the event, and charts keep their history. If a change removes or renames fields, Ema asks you to confirm in Review breaking changes, because removed fields can break workflows and charts that use them.
- Edit a shared event. A shared event's fields are managed where it's shared from, so you can view it on an AI Employee but not edit it there. On the Group or Workspace Events panel, saving publishes the change to every AI Employee that uses it.
- Stop recording. On an event that belongs to the AI Employee, select Stop recording. It stops after you publish. Remove its Emit Event Agent from the workflow too, or publishing fails. Past entries and charts stay.
- Remove a shared event from an AI Employee. Select Remove from AI Employee. Entries it already recorded stay available in Metrics.
Export and import events
Group and Workspace Events panels can copy event definitions between Groups or Workspaces.
- Export. Select one or more published events, then Export selected. Ema saves their definitions to a JSON file. Charts and recorded entries are not included.
- Import. Select Import events and choose a file made with Export selected, smaller than 1 MB. Review the destination, then confirm. The events are added with their fields. Existing events are not overwritten.
To move an AI Employee together with its events and charts, use the AI Employee's own export instead. See AI Employee export and import.
Who can manage events
- On an AI Employee: anyone who can edit the AI Employee.
- On a Group or the Workspace: people who can edit metrics. Seeing events from AI Employees across the Workspace also needs Workspace-wide Metrics access.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| No Events button on the Metrics tab. | Custom events are not turned on for your Workspace. Ask your Ema contact. |
| The status is Recording but the chart is empty. | No published run has reached the Emit Event Agent in the chart's date range. Test runs don't record entries. Run the published AI Employee, then check the dashboard's date range. |
| Some runs didn't record an entry. | A required field had no value in those runs. Check the step that feeds it, or make the field optional. |
| The event doesn't appear in the Emit Event Agent's Event list. | Only events in this AI Employee's Events panel appear. Add or join the event there first. |
| Publishing fails after you changed an event's fields. | The Emit Event Agent still uses the old fields. Open it, select Reload event schema, connect any required fields, save, and publish again. |
| Publishing fails after you selected Stop recording. | The workflow still has an Emit Event Agent for that event. Remove it, then publish. |
| A shared event shows Doesn't match. | This AI Employee doesn't produce every field the event needs. The hint lists the missing fields. Add those outputs to a step, then try again. |
| Import says "This JSON is not an event export." | The file wasn't made with Export selected. Export the events again from the source Group or Workspace. |
What's next
- Emit Event Agent: the agent's configuration and output in detail.
- Building a custom metrics view: build and publish charts on an AI Employee's Metrics tab.
- Building a Workspace metrics view: chart events across the whole Workspace.
- Code Agent: write the scripts that can call
emit_event.