---
updatedAt: 2026-11-02T20:49:09.000Z
agentTools:
  projectIndex: https://docs.getmontecarlo.com/llms.txt
---

# Agent Validation Monitor

Enforce row-level validation rules over agent spans with Monitors as Code.

## Overview

Agent validation monitors enforce row-level rules over an agent's spans — alerting when spans violate a predicate (for example, a required field is null, or a score falls outside an allowed range). Like trajectory monitors, they are rule-based: the logic lives in a single `alert_condition` predicate tree, evaluated over a `time_filter` window, rather than in `alert_conditions`.

> 📘 **Reference scope**
>
> This page covers MaC YAML configuration. For how validation monitoring works, see [Agent Validation Monitors](https://docs.getmontecarlo.com/docs/agent-validation-monitors).

MaC key: `agent_validation`.

> 📘 **Author by export.** The `alert_condition` predicate tree is intricate. The most reliable way to get its exact shape is to build the monitor in the Monte Carlo UI and export it with `montecarlo monitors export`, then manage the exported YAML.

## Quick Start

```yaml
montecarlo:
  agent_validation:
    - name: prompts_not_null
      description: Alert when an agent span has a null prompt
      agent: my-otel-agent # the agent's service_name
      alert_condition:
        operator: AND
        conditions:
          - type: UNARY
            predicate:
              name: "null"
            value:
              - field: prompts
      time_filter:
        time_field:
          field: ingest_ts
        lookback_in_hrs: 10
      schedule:
        type: fixed
        interval_minutes: 60
        start_time: "2025-01-01T00:00:00+00:00"
      domains:
        - my-domain
```

## Configuration

<Cards columns={1}>

<Card title="agent — the agent to monitor">

`string` · required

The agent whose spans the monitor reads. Agent monitors name an `agent` instead of a table; the warehouse source is derived from it. The value takes one of two forms, told apart by its shape:

- **Warehouse platform agents** (e.g. Snowflake Cortex, Databricks) — a `<database>:<schema>.<name>` reference, where `<name>` is the agent's display name when it has one (otherwise its underlying identifier). No `trace_table`.
- **OpenTelemetry agents** — the agent's bare `service_name`. By default the OpenTelemetry trace store is resolved automatically; set `trace_table` only when the spans live in a specific warehouse table.

```yaml
agent: my-otel-agent
```

</Card>

<Card title="trace_table — warehouse trace table for an OTel agent">

`string` · optional

`<database>:<schema>.<table>` naming the warehouse trace table that holds an OpenTelemetry agent's spans. Required when the spans live in your warehouse, or when the warehouse holds more than one OpenTelemetry trace table. Omit it for platform agents and for agents resolved from the default OpenTelemetry trace store.

```yaml
trace_table: "ingest:opentelemetry.traces"
```

</Card>

<Card title="alert_condition — the validation predicate">

`object` · required

The predicate tree spans must satisfy (or are flagged for violating). A set of `conditions` combined by a boolean `operator` (`AND` / `OR`); each condition is a predicate over span fields. Leaf predicates are unary (`type: UNARY`, e.g. is-null), binary (`type: BINARY`, e.g. comparison), or raw SQL (`type: SQL`), and groups can nest.

```yaml
alert_condition:
  operator: AND
  conditions:
    - type: UNARY
      predicate:
        name: "null"
      value:
        - field: prompts
```

</Card>

<Card title="time_filter — evaluation window">

`object` · required

The lookback window the condition is evaluated over. `time_field` must be the `ingest_ts` field; `lookback_in_hrs` must be at least 1.

```yaml
time_filter:
  time_field:
    field: ingest_ts
  lookback_in_hrs: 10
```

</Card>

<Card title="exception_primary_key_column — dedup key for exceptions">

`string` · optional

The span column used to identify and deduplicate exceptions across runs (for example, `span_id`). Lets the monitor track the same offending row over time rather than re-alerting on it.

```yaml
exception_primary_key_column: span_id
```

</Card>

<Card title="is_agent_trace_aggregation — score whole traces">

`boolean` · optional

Evaluate the validation at the trace grain rather than per span. When set, only the `agent` span filter is allowed — span-level refinements (`workflow`/`task`/`span_name`) are rejected. Include it in the template to re-apply at the same grain.

```yaml
is_agent_trace_aggregation: true
```

</Card>

<Card title="filters — additional span filtering">

`object` · optional

A predicate tree (`FilterGroup`) that further restricts which spans are validated, beyond the agent and the alert condition.

</Card>

<Card title="agent_span_filters — narrow to a workflow, task, or span">

`array of objects` · optional

Refines the monitor to specific spans (`workflow`, `task`, `span_name`, each an object with a `value`). The agent is already set by `agent`. With `is_agent_trace_aggregation: true`, only the `agent` dimension is allowed here.

```yaml
agent_span_filters:
  - workflow:
      value: checkout
```

</Card>

<Card title="schedule — when the monitor runs">

`object` · required

`type` (`fixed` or `manual`), `interval_minutes`, `start_time`, `timezone`. Dynamic schedules are not supported for validation monitors.

```yaml
schedule:
  type: fixed
  interval_minutes: 60
  start_time: "2025-01-01T00:00:00+00:00"
```

</Card>

<Card title="auto_tuning — override auto-apply tuning for this monitor">

`boolean` · optional

Force auto-apply tuning on (`true`) or off (`false`) for this monitor, overriding the account or domain default. Omit to inherit. See [Bayes monitor tuning](https://docs.getmontecarlo.com/docs/tuning-agent#per-monitor-auto-apply-override).

```yaml
auto_tuning: false
```

</Card>

<Card title="Common fields">

The shared rule-monitor envelope:

- **`name`** `string` · optional — unique identifier (auto-generated if omitted); renaming creates a new monitor.
- **`description`** `string` · optional — max 512 characters.
- **`warehouse`** `string` · optional — UUID or name; overrides the `montecarlo.yml` default.
- **`connection_name`** `string` · optional — query engine to use within the warehouse.
- **`timeout`** `integer` · optional — query timeout in seconds.
- **`notes`** `string` · optional — shown in the UI, not in notifications.
- **`audiences`** `array of strings or mappings` · optional — notification channels. An entry can narrow an audience to specific triage priorities; see [Routing alerts by triage priority](https://docs.getmontecarlo.com/docs/notifications-v2#routing-alerts-by-triage-priority).
- **`failure_audiences`** `array of strings` · optional — notification channels for run failures.
- **`priority`** `enum` · optional — `P1`–`P5`.
- **`event_rollup_count`** `integer` · optional — minimum 2; roll up repeated breaches into one incident.
- **`tags`** `array of objects` · optional — `name` (required) + `value` (optional).
- **`data_quality_dimension`** `enum` · optional — `ACCURACY` · `COMPLETENESS` · `CONSISTENCY` · `TIMELINESS` · `UNIQUENESS` · `VALIDITY`.
- **`domains`** `array of strings (exactly one entry)` · required when creating a monitor — required on all accounts, regardless of when the account was created.

</Card>

<Card title="auto_triage — override auto-triage for this monitor">

`boolean` · optional

Force auto-triage on (`true`) or off (`false`) for this monitor, overriding the account or domain default. Omit to inherit. See [Bayes triage](https://docs.getmontecarlo.com/docs/triage-agent#per-monitor-override).

```yaml
auto_triage: false
```

</Card>

</Cards>

<Accordion title="Deprecated fields">

| Field | Use instead |
|-------|-------------|
| `resource` | `warehouse` |
| `domain_uuids` | `domains` |
| `labels` | `audiences` |

</Accordion>

## Examples

### OpenTelemetry agent — null check

Alert when an agent span has a null `prompts` value, scanning the last 10 hours and deduplicating exceptions by `span_id`.

```yaml
montecarlo:
  agent_validation:
    - name: prompts_not_null
      description: Alert when an agent span has a null prompt
      agent: my-otel-agent
      alert_condition:
        operator: AND
        conditions:
          - type: UNARY
            predicate:
              name: "null"
            value:
              - field: prompts
      time_filter:
        time_field:
          field: ingest_ts
        lookback_in_hrs: 10
      exception_primary_key_column: span_id
      schedule:
        type: fixed
        interval_minutes: 60
        start_time: "2025-01-01T00:00:00+00:00"
      domains:
        - my-domain
```

### Platform agent — trace-level validation

Validate at the trace grain on a warehouse platform agent. With `is_agent_trace_aggregation`, only the `agent` span filter is allowed.

```yaml
montecarlo:
  agent_validation:
    - name: cortex_trace_completion_present
      description: Alert when a trace has no completion
      agent: "ANALYTICS:AGENTS.support_cortex_agent"
      is_agent_trace_aggregation: true
      alert_condition:
        operator: AND
        conditions:
          - type: UNARY
            predicate:
              name: "null"
            value:
              - field: completions
      time_filter:
        time_field:
          field: ingest_ts
        lookback_in_hrs: 24
      schedule:
        type: fixed
        interval_minutes: 120
        start_time: "2025-01-01T00:00:00+00:00"
      domains:
        - my-domain
```

## Troubleshooting

### Agent source

* **Omitting `agent`.** Every agent monitor requires an `agent`. A monitor without one fails validation.
* **Platform reference not found / ambiguous.** A `<database>:<schema>.<name>` reference must match exactly one registered agent in the target account and warehouse. A display name shared by two agents in a schema is ambiguous — use the underlying endpoint identity. Cross-account: register the agent first.
* **Setting `trace_table` for a default-store agent.** Redundant and rejected when the OpenTelemetry trace store resolves automatically. Omit it.

### Validation specifics

* **Using `alert_conditions`.** Validation monitors have no `alert_conditions` field — the predicate goes in the singular `alert_condition`.
* **Empty `alert_condition`.** The predicate tree must contain at least one condition.
* **`time_filter` field other than `ingest_ts`.** The `time_field` must be `ingest_ts`, and `lookback_in_hrs` must be at least 1.
* **Span-level filters with trace aggregation.** With `is_agent_trace_aggregation: true`, only the `agent` span filter is allowed — `workflow`/`task`/`span_name` are rejected.
* **A dynamic schedule.** Validation monitors don't support `schedule.type: dynamic`.
* **Forgetting PUT semantics on updates.** Updating a monitor replaces its full configuration — omitted fields revert to defaults, including `is_agent_trace_aggregation`. Always specify the complete desired configuration.