Enrichments

An enrichment runs an LLM prompt over your traces or sessions and extracts structured fields from each one — a category, a flag, a number, a list — that you define up front. Where a judge answers “how good was this?”, an enrichment answers “what is this?”: intent, language, product area, escalation risk, anything you can describe in a prompt.

At a glance


Where	Enrichments in the sidebar; run history under Activity
Targets	A trace or a session (conversation rollup — see Traces & sessions)
Output	Typed fields stored per target; filterable columns on the Traces page
Runs	Manual (up to 500 targets per run) or continuous on ingest (up to 500 targets per enrichment per UTC day)
Needs	An LLM connection (Settings → Connections) — a run without one fails with a clear error

Create an enrichment

Define what to extract

Open Enrichments and create a new one. Give it a name, pick the target type (trace or session), and write the prompt — plain instructions telling the model what to look at and what to extract.

Declare the output fields

Each output field is a typed column the model must fill in:

Field property	Meaning
Key	The field’s identifier — how it appears as a column/filter and in the API.
Label	Display name in the UI.
Value type	`string`, `number`, `boolean`, `enum`, or `array`.
Enum values	For `enum` (and `array`) fields: the allowed values the model must choose from.

Values are validated and coerced on write — a boolean field stores true/false, a number field stores a numeric value, an array field stores a list.

Narrow the targets (optional)

Prerequisites restrict which traces/sessions are eligible at all:

Created after a date.
Matching topics.
Score conditions — e.g. only targets whose score on a given metric is gte/lte/eq/ gt/lt a value, with a missing-score policy of skip (default) or include for targets that haven’t been scored yet.

Save

New enrichments start as drafts — defined but not running anything, so creating one never spends tokens.

LLM prompt and external-API are the executable kinds. Custom-Python enrichments can be authored but don’t run — a run over one fails immediately with a clear “not executable” error rather than doing nothing silently.

Run it

Click Run now on an enrichment. You can point the run at:

everything eligible (prerequisites applied),
a filter — the same filter vocabulary as the Traces page, or
a specific dataset — only its member sessions are enriched.

A manual run resolves at most 500 targets; it enqueues, then progresses queued → running → completed (or completed_with_failures / failed). Each target is one LLM call, so a 500-target run is 500 calls — mind your provider costs.

Every run — manual or continuous — appears in the Activity feed with live progress counts and attribution (who started it, or Automated for on-ingest runs).

Where the outputs go

Traces page — each enrichment field becomes a discoverable column and filter, so you can slice traffic by intent = refund_request or escalation_risk = true the same way you filter by status or score.
Datasets — from an enrichment you can create a dataset of all sessions where a field has a given value (e.g. every category = billing session). Filter-based datasets can also carry an enrichment condition directly, and stay in sync as new outputs land.
Judges — enrichment outputs reach judges through datasets: build a dataset from an enrichment field, then target a judge’s eval run at that dataset. The enrichment decides which sessions get scored; the judge’s own evidence settings decide what it reads.

How it works

When a run starts, a worker resolves the run’s LLM provider from the agent’s configured connections (an enrichment can pin a specific connection, otherwise the agent default is used), then calls the model once per target with your prompt and the target’s content. Extracted values are validated against your declared field types and stored per target; the same target re-enriched later updates in place rather than duplicating. Outputs are kept alongside your other trace signal, so filtering and dataset membership stay fast even at high volume.

⚠️

No LLM connection, no run. Enrichments always use the agent’s LLM connection (Settings → Connections). If none is configured, a run fails with an explicit error — nothing is silently skipped or fabricated. Configure a connection before enabling continuous mode.

Managing enrichments

Action	Effect
Edit	Updates the definition; prompt changes create a new immutable version (the new one becomes current, history is kept).
Disable	Returns the enrichment to draft: no manual or continuous runs, and the on-ingest trigger is reset to manual. Existing outputs remain.
Delete	Hard-deletes the enrichment, all versions, runs, and outputs — irreversible.

API reference

Route	Purpose
`GET /user-enrichments`	List enrichments (filter by name, mode, status, target type).
`POST /user-enrichments`	Create (starts as `draft`).
`PATCH /user-enrichments/{id}`	Edit, or set `status` to `enabled` / `draft` (disable).
`DELETE /user-enrichments/{id}`	Hard-delete the enrichment, its versions, runs, and outputs.
`POST /user-enrichments/{id}/versions`	Publish a new version (older versions stay immutable).
`POST /user-enrichments/{id}/deployments`	Enable continuous (on-ingest) triggering.
`POST /user-enrichment-runs`	Start a manual run (optional `filter` or `dataset_id`).
`GET /user-enrichment-runs/{run_id}`	Run status plus a sample of outputs (`?sample=N`, default 20, max 200).
`GET /enrichment-fields`	Output fields that have computed values (drives Traces filters and the dataset picker).
`POST /user-enrichments/{id}/dataset`	Create a dataset from an output field/value.

Troubleshooting

Symptom	Cause → fix
Run immediately `failed` with a connection error	No LLM connection is visible to the agent → add one under Settings → Connections.
Run `failed` with “not executable”	The enrichment is a custom-Python definition — only LLM prompt and external-API enrichments execute today.
Continuous enrichment stopped mid-day	The 500-targets-per-day budget for that enrichment is spent; it resumes the next UTC day. Run manually if you need more today.
New traffic isn’t being enriched	The enrichment is in draft, or continuous mode isn’t enabled → Configure it and turn on Continuous (on ingest).
Fields missing on the Traces page	Fields only appear once at least one output value exists — run the enrichment first.