Custom tags (trace metadata)

Custom tags add your own business data to conversations, such as payment type, card action, or customer ID. Use them to chart, group, and filter conversations by that data in Custom dashboards. The prebuilt Insights dashboards don’t use custom tags.

Add tags

You can add tags in three places. Use the one that holds the data you need.

Where	How	Use it when
In the agent	Set `_meta.<key>` at any point, or map a tool’s result into `_meta` keys after the call.	The agent knows the value during the conversation, for example the action a tool took.
In Settings → Trace Dimensions	Name the session variables to copy onto every event, up to 100 keys.	The value already exists as a session variable.
From your app	Pass `customAttributes` when the SDK starts a session.	Your app knows the value before the conversation starts, for example a customer segment.

Example: tag a conversation in ABL

The following agent sets a tag when the session starts, and two more tags from a tool result.

ON_START:
  SET: _meta.assistant_mode = "multi_agent"

TOOLS:
  lock_card(customer_id: string, card_id: string) -> object
    on_result:
      set:
        _meta.card_action: "lock"
        _meta.card_action_status: result.output.status

Where tags show up

The platform writes tags on every event and on the session summary. In a custom dashboard widget or in Analytics Explorer → Query, you can group and filter by them. The widget editor lists them in the Custom dimensions panel. The platform stores tags in the custom_dimensions column, a map of string keys. In a widget query, read one as custom_dimensions['payment_type'].

Limits

Limit	Value
Keys per conversation	50
Size per value	1 KB
Session variables in Trace Dimensions	100 keys

By default, the platform rejects values that look like personal data. Don’t put personal data in tags.

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Custom tags (trace metadata)

Add tags

Example: tag a conversation in ABL

Where tags show up

Limits

​Add tags

​Example: tag a conversation in ABL

​Where tags show up

​Limits

Add tags

Example: tag a conversation in ABL

Where tags show up

Limits