> Source: https://builder.ema.ai/v2/agent-reference/emit-event
> Title: Emit Event Agent

# Emit Event Agent

The Emit Event Agent records one entry of a [custom event](/builder/v2/builder-guides/custom-events) each time it runs. You pick the event and connect each of its fields to an output from an earlier step or to a constant. It makes **no LLM call**, so it adds no token usage.

The agent belongs to the **Planning & Resources** group in the agent library. Its base type is `emit_event`. It appears in the library when custom events are turned on for your Workspace.

## When to use it

-   Count a business outcome the built-in metrics don't capture, such as an invoice approved or a claim paid.
-   Save values from a run, such as an amount or a status, so you can chart and filter by them on the Metrics tab.
-   Record the same shared event from several AI Employees, so their numbers add up in Group charts.

To record several entries in one run, or values that need logic to work out, call `emit_event` from a [Code Agent](/builder/v2/agent-reference/code-agent) instead.

## Before you add it

The event must already be on the AI Employee's Events panel (**Metrics** tab, then **Events**), either as the AI Employee's own event or as a shared event it uses. See [Create an event](/builder/v2/builder-guides/custom-events#create-an-event).

## Configuration

Setting

What it does

**Event**

The event to record. Lists the events on this AI Employee's Events panel.

One row per field

Connect an output from an earlier step, choose **Constant** and enter a fixed value, or leave the field unbound. Unbound optional fields are left out of the entry.

Ema checks the configuration before you can publish:

-   Every required field must be connected or set to a constant.
-   A constant must match the field's type. Numbers must be valid numbers. Dates use `YYYY-MM-DD`, and datetimes need a timezone.
-   The selected event must still be available to the AI Employee.

The Workspace, AI Employee, run, and step that recorded an entry are added automatically. One entry is recorded each time the step runs.

### When the event's fields change

If someone changes the event's fields after you configured the agent, the agent shows that the fields changed. Select **Reload event schema**:

-   Connections and constants for fields that still exist with the same type are kept.
-   Connections for removed fields, or fields whose type changed, are cleared. Ema lists them.
-   Connect any new required field before you publish.

## Output

On a published run, the agent returns a receipt for the recorded entry:

```json
{
  "event_id": "5f0d1c2e-8a4b-4c3e-9f21-7b6d2e1a9c40",
  "accepted_at": "2026-11-09T19:42:07.512Z",
  "alias": "Invoice processed"
}
```

Field

Purpose

`event_id`

The ID of the recorded entry.

`accepted_at`

When Ema accepted the entry.

`alias`

The event's alias on this AI Employee.

## Test runs and evaluations

Test runs in the editor and evaluation runs don't record entries. The agent completes and shows the entry it would have recorded, so you can check the values before you publish:

```json
{
  "emitted": false,
  "preview": true,
  "alias": "Invoice processed",
  "payload": { "invoice_id": "INV-1042", "amount": 1250, "status": "approved" }
}
```

## When it fails

The step fails, and no entry is recorded, when:

-   A required field has no value in that run.
-   A connected value doesn't match the field's type, for example text in a number field.
-   Custom events are turned off for the Workspace.

Check the run in the [debug logs](/builder/v2/testing-operations/debug-logs) to see which field caused it.

## What's next

-   [Tracking custom events](/builder/v2/builder-guides/custom-events): define events, share them, and chart them.
-   [Code Agent](/builder/v2/agent-reference/code-agent): record events from a script with `emit_event`.
-   [Building a custom metrics view](/builder/v2/builder-guides/custom-metrics-views): chart the entries on the Metrics tab.
