Deep Analysis YAML reference

The Deep Analysis configuration is a YAML document attached to an agent or a campaign. It defines what a language model extracts from each conversation and how the results are charted. You edit it in the agent's Analytics section in Advanced mode, or in a campaign's YAML Analytics dialog on the Python campaigns screen.

This page is the field-by-field reference for that document. For how analyses run, where dashboards appear, and how to read and drill into them, see Deep Analysis — this page does not repeat that workflow.

Top-level structure

A configuration has three required sections — scheduling_rules, analysis_types, and visualization — plus two optional top-level keys.

version: "2.0"
llm_integration_name: "My OpenAI"
scheduling_rules:
  cron_exp: "0 0 * * *"
  depth: 30
analysis_types:
  - ...
visualization:
  tabs:
    - ...

Key	Required	What it does
version	No	A free-text version string for your own tracking. The product does not act on it.
llm_integration_name	No	The name of the integration whose language model evaluates conversations. When set, the analysis uses that integration; when omitted, it falls back to the agent's own OpenAI integration.
scheduling_rules	Yes	When the analysis runs and how much history it processes. See Scheduling rules.
analysis_types	Yes	The metrics extracted from each conversation. See Analysis types.
visualization	Yes	The tabs and plots shown on the dashboard. See Visualization.

Indent with exactly two spaces.

Scheduling rules

scheduling_rules controls the run schedule and the history window. Both keys are required.

scheduling_rules:
  cron_exp: "0 0 * * *"
  depth: 30

Key	Type	What it does
cron_exp	string	A cron expression for when the scheduled run starts. The example "0 0 * * *" runs daily at midnight.
depth	integer	How many days of conversation history the run processes. Conversations older than depth days are not evaluated.

Analysis types

analysis_types is a list. Each entry is one analysis task — a single language-model call with its own prompt and its own set of metrics. List several entries when you want to evaluate different aspects of a conversation with separate prompts.

analysis_types:
  - id: SatisfactionAnalysis
    order: 1
    description: Evaluate user satisfaction from tone and flow of conversation.
    prompt_template: |
      # Task
      {task}
      # Chat history to analyze
      {chat_history}
      # Response JSON schema
      {formatting}
    prompt_parts:
      task: |
        Evaluate user satisfaction from tone and flow of conversation.
    llm_metrics:
      - ...
    code_metrics:
      - ...

Key	Required	What it does
id	Yes	A unique identifier for the analysis task.
order	Yes	An integer that sets the order analysis tasks run in.
description	No	A free-text note describing the task.
prompt_template	Yes	The prompt sent to the language model, with placeholders filled in at run time. See Prompt template placeholders.
prompt_parts	Yes	The text that fills the {task} and {real_data} placeholders. See Prompt parts.
llm_metrics	Yes	The fields a language model evaluates. See LLM-based metrics.
code_metrics	No	The fields computed by a Python expression, with no language model. See Code-based metrics.

Prompt template placeholders

prompt_template is the literal prompt text. The product substitutes these placeholders before sending it to the model:

Placeholder	Filled with
{task}	The task text from prompt_parts.
{real_data}	The real_data text from prompt_parts. Empty when real_data is not set.
{chat_history}	The conversation messages, formatted for the model.
{conversation_result}	The session's collected conversation result as JSON, or NO CONVERSATION RESULT when there is none.
{formatting}	The JSON schema the model must return, generated from the task's llm_metrics.

Include only the placeholders you need. A template that does not reference {conversation_result}, for example, omits it.

Prompt parts

prompt_parts holds the reusable text the template's placeholders pull in.

Key	Required	Fills
task	Yes	The {task} placeholder — the instruction describing what to analyze.
real_data	No	The {real_data} placeholder — extra context or reference data for the task.

LLM-based metrics

Each entry in llm_metrics is one field a language model evaluates. The model returns a value for the field in the type you declare, and that value becomes a category you can chart and drill into.

llm_metrics:
  - id: sentiment
    name: Sentiment Analysis
    kind: llm
    type: Literal["positive", "neutral", "negative"]
    description: Human's overall sentiment.
    prompt: |
      Classify the Human's overall sentiment based on the conversation:
        - positive: The user was satisfied at the end of the conversation.
        - neutral: The user was neither satisfied nor dissatisfied.
        - negative: The user was dissatisfied at the end of the conversation.
    values:
      - id: positive
        name: Positive
        color: green
      - id: neutral
        name: Neutral
        color: gray
      - id: negative
        name: Negative
        color: red

Key	Required	What it does
id	Yes	A unique identifier for the metric. The visualization references metrics by this id, and it is the key in the model's returned JSON.
name	Yes	The display name shown for the metric on the dashboard.
kind	Yes	llm for a language-model field.
type	Yes	The Python type the model must return. See Metric types.
description	Yes	A short description of the metric, shown on the dashboard.
prompt	Yes	The instruction the model follows to produce this field's value. For a fixed-choice metric, define each value with explicit criteria — vague prompts produce inconsistent classifications.
values	No	For a fixed-choice (Literal) type, the display name and chart color of each possible value. See Metric values.

Metric types

The type key is the Python type annotation the model's returned value must satisfy. Common types:

type	The model returns
Literal["a", "b", "c"]	Exactly one value from the listed set — a category you can count and chart.
str	Free text, such as a reasoning or explanation field.
bool	A true/false flag.
list[str]	A list of text values, such as topics or complaints.
list[str] | None	A list, or nothing when there is none to report.

Use a Literal type for any field you want to chart as a distribution. Use str for an explanation field that you attach to each conversation with a plot's additional_info. Free text, booleans, and lists are recorded per conversation but are not charted as category distributions.

Metric values

values is used only with a Literal type. List one entry per value in the literal, so each value gets a display name and a chart color.

Key	Required	What it does
id	Yes	The value, matching one of the options in the Literal type.
name	Yes	The display name for the value on charts and cards.
color	No	The chart color for the value. See Colors. Values without a color get one automatically.

Code-based metrics

Each entry in code_metrics is a field computed by a single Python expression, with no language model involved. Use them to derive a value from the conversation data — for example, to extract text or a tag for breaking results down.

code_metrics:
  - id: agent_messages
    name: Agent Messages
    kind: code
    description: Text of every AI message in the conversation.
    expression: "'\\n'.join([m.text for m in dialogs[0].messages if m.role.value == 'AI'])"

Key	Required	What it does
id	Yes	A unique identifier for the metric, referenced the same way as an LLM metric.
name	Yes	The display name for the metric.
kind	Yes	code for a code-based field.
description	No	A short description of the metric.
expression	Yes	A Python expression evaluated against the conversation data. Its result is the field's value.

The expression runs after the language-model metrics, so it can reference any LLM metric in the same task by its id. It can also reference dialogs (the conversation) and the built-in per-session statistic values listed below.

Statistic values available to expressions

A code expression can reference these per-session values by name:

Name	Type	What it holds
messages_count	number	Total number of messages.
is_operator_session	bool	The session was transferred to an operator.
is_resolved_by_operator	bool	The session was resolved by an operator.
operator_message_count	number	Number of messages from the operator.
operator_answered	bool	The operator replied to the person.
human_message_count	number	Number of messages from the user.
ai_message_count	number	Number of messages from the agent.
ai_not_answered	bool	The agent did not reply; the last message is from the human.
human_not_answered	bool	The person did not reply; the last message is from the agent, but human_message_count is greater than 0.
ai_spam	bool	The agent sent many messages the person did not respond to.
no_communication	bool	The agent sent messages but the human sent none.

Visualization

visualization defines the dashboard: the tabs across the top and the plots inside each tab. It has one required key, tabs.

visualization:
  tabs:
    - id: general_analysis
      title: General Analysis
      plots:
        - ...

Tabs

tabs is a list. Each entry is one tab on the Deep Analysis screen.

Key	Required	What it does
id	Yes	A unique identifier for the tab.
title	Yes	The tab label shown on the screen.
plots	Yes	The charts in the tab. See Plots.

Plots

plots is a list. Each entry is one chart — either a trend chart or a summary card.

plots:
  - id: sentiment_summary
    kind: summary
    type: detailed_bars
    title: Sentiment
    metrics:
      - id: sentiment
        features:
          - id: unit
            aggregation: sum
    additional_info: sentiment_thoughts

Key	Required	What it does
id	Yes	A unique identifier for the plot.
title	Yes	The chart title shown on the screen.
kind	Yes	trend for a trend chart over time, or summary for a summary card aggregating the whole period.
type	Yes	The chart style. See Plot types.
metrics	Yes	The metrics the chart displays. See Plot metrics.
additional_info	No	The id of a metric whose per-conversation value is shown as the explanation text under each session in the Details view. Typically points at a str reasoning metric.

Plot types

kind	type	Renders as
trend	bar_time_series	A trend chart with one bar series per category value, grouped by the selected granularity.
trend	line_time_series	A trend chart with one line series per category value.
summary	detailed_bars	A summary card with one row per category value and a proportional bar.

Plot metrics

Each entry in a plot's metrics binds one configured metric (by its id) to the chart and says how to aggregate it.

metrics:
  - id: sentiment
    features:
      - id: unit
        aggregation: sum
        percentage: true
    filters:
      - metric_id: risk_class
        metric_value: no_risk
    values:
      - id: positive
        color: green
      - id: negative
        color: red

Key	Required	What it does
id	Yes	The id of the metric to chart.
features	Yes	How the metric is aggregated. See Features.
filters	No	Restricts the chart to conversations where another metric equals a given value. See Filters.
values	No	Overrides the display order and color of category values for this plot only. Each entry is { id, color }, or a bare value id string.

Features

Each features entry sets how the metric's values are counted.

features:
  - id: unit
    aggregation: sum
    percentage: true
    min_value: 1.33

Key	Required	What it does
id	Yes	The value to aggregate. Use unit to count conversations: each conversation contributes 1, so unit with sum gives the number of conversations in each category.
aggregation	Yes	How to combine the values: sum, count, or average.
percentage	No	When true, shows the result as a percentage of the total rather than a raw count. Defaults to false.
min_value	No	Hides a category value whose aggregated result is below this number.

Filters

Each filters entry narrows the chart to conversations where another metric has a specific value. Use a filter to chart one metric within a subset defined by another — for example, sentiment only among conversations classified as no_risk.

Key	Required	What it does
metric_id	Yes	The id of the metric to filter on.
metric_value	Yes	The value that metric must have for a conversation to be included.

A filter that points at the metric of an earlier plot metric also nests the filtered metric as a sub-entry under that value in the Details view — the sub-entries you can click to narrow the selection.

Colors

The color keys on metric values and plot-metric values accept one of these names:

red, blue, green, orange, purple, gold, cyan, magenta, lime, pink, brown, olive, teal, navy, maroon, coral, indigo, violet, turquoise, gray, yellow.

Where results appear

After a calculation runs, the configuration drives the Deep Analysis screen:

• Each tab becomes a tab on the screen; each plot becomes a trend chart or a summary card in that tab.
• A metric's name and description label its chart and card; each value's name and color label and color the series and rows.
• A summary card's Details view lists the conversations behind each value. A plot's additional_info metric supplies the explanation text shown under each session, and a filters-based sub-entry becomes a clickable category breakdown.

Related pages

• Deep Analysis — read and drill into the dashboards this configuration produces
• Conversation result field types — the per-session fields available to {conversation_result}
• Advanced mode — the agent's Analytics section where the configuration lives
• Python campaigns — attach a configuration to a campaign
• Sessions — read the conversations behind a result