> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognigy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Assertions

<a href="/release-notes/2025.19"><Badge className="version-badge" color="blue">Updated in 2025.19</Badge></a>

*Assertions* are validation checks that verify the AI Agent's responses and different aspects of the Flow for each Step during a Playbook run.

## How to Use Assertions

Assertions include an input field where you can provide the text or data you want to validate during the Playbook run. Assertions are case-sensitive. The text, Intent names, Slot names, and data fields that you enter in the input field must match exactly what you want to validate. Specific assertion types include an option to validate only a portion of the provided text or data:

* **Use fuzzy search** — for text assertions.
* **Use partial comparison** — for data and context assertions.

The fuzzy search functionality handles case-insensitive matches, differences in spaces, tab stops, and newlines, and escaped characters.

<Accordion title="Fuzzy Search Examples">
  | Pattern    | Feature                   | Matches                                     |
  | ---------- | ------------------------- | ------------------------------------------- |
  | `My order` | **Case Insensitivity**    | `my order`, `MY ORDER`                      |
  |            | **Differences in spaces** | <pre><code>My   order</code></pre>          |
  |            | **Newlines**              | <pre><code>My<br /><br />order</code></pre> |
  |            | **Escaped Characters**    | `My\norder`, `My\torder`                    |
</Accordion>

You can also invert the assertion check with the **Invert assertion** option. This option switches the assertion check to validate the absence of the defined value. Inverted assertions must also match the exact text or data provided in the assertion. You can activate both **Invert assertion** and **Use fuzzy search** to validate the absence of a portion of the provided text or data, for example, only the `"status": "active"` JSON property or the word `"error"` in the AI Agent's response.

## Assertion Types

### Text Assertion

Validates text in the AI Agent's response against the expected text or pattern provided in the input field.

| Parameter        | Type        | Description                                                                                    |
| ---------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| Invert assertion | Option      | Sets the assertion to validate the absence of the text or pattern provided in the input field. |
| Use fuzzy search | Option      | Allows partial matches in the AI Agent's response.                                             |
| Text             | Input field | Sets the exact text or pattern to validate.                                                    |

#### Examples

<AccordionGroup>
  <Accordion title="Exact Match">
    In this example, configure the assertion as follows:

    | Parameter        | Value                           |
    | ---------------- | ------------------------------- |
    | Invert assertion | Deactivated                     |
    | Use fuzzy search | Deactivated                     |
    | Text             | `Your order has been confirmed` |

    Validates that `Your order has been confirmed` is present in the AI Agent's response.
    Fails if `We have received your order` is in the AI Agent's response.
  </Accordion>

  <Accordion title="Fuzzy Search">
    In this example, configure the assertion as follows:

    | Parameter        | Value       |
    | ---------------- | ----------- |
    | Invert assertion | Deactivated |
    | Use fuzzy search | Activated   |
    | Text             | `"order"`   |

    Validates that `Your order has been confirmed` and `We have received your order` are in the AI Agent's response.
    Fails if `We are preparing your purchase` is in the AI Agent's response.
  </Accordion>

  <Accordion title="Inverted Assertion">
    In this example, configure the assertion as follows:

    | Parameter        | Value     |
    | ---------------- | --------- |
    | Invert assertion | Activated |
    | Use fuzzy search | Activated |
    | Text             | `"error"` |

    Validates that the AI Agent's response doesn't include `error`, for example, `Your order will be shipped shortly`.
    Fails if the AI Agent's response includes `error`, for example, `We found an error while processing your order`.
  </Accordion>
</AccordionGroup>

### Data Assertion

Validates the AI Agent message's data fields and JSON structures against the data provided in the input field. If the AI Agent's response doesn't include any data fields, the Assertion checks data fields in the user input.

| Parameter              | Type        | Description                                                                                                     |
| ---------------------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| Invert assertion       | Option      | Sets the assertion to validate the absence of the JSON structure provided in the input field or the user input. |
| Use partial comparison | Option      | Allows matches of a subset of the data structure to validate.                                                   |
| Data                   | Input field | Sets the data structure to validate in JSON format.                                                             |

#### Examples

<AccordionGroup>
  <Accordion title="Exact Match">
    In this example, configure the assertion as follows:

    <table>
      <thead>
        <tr>
          <th>Parameter</th>
          <th>Value</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Invert assertion</td>
          <td>Deactivated</td>
        </tr>

        <tr>
          <td>Use partial comparison</td>
          <td>Deactivated</td>
        </tr>

        <tr>
          <td>Data</td>

          <td>
            ```json theme={null}
            {
            "userId": "12345",
            "status": "active",
            "timestamp": "2024-01-01T10:00:00Z"
            }
            ```
          </td>
        </tr>
      </tbody>
    </table>

    Validates only the exact JSON object provided in the input field.
  </Accordion>

  <Accordion title="Partial Comparison">
    In this example, configure the assertion as follows:

    <table>
      <thead>
        <tr>
          <th>Parameter</th>
          <th>Value</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Invert assertion</td>
          <td>Deactivated</td>
        </tr>

        <tr>
          <td>Use partial comparison</td>
          <td>Activated</td>
        </tr>

        <tr>
          <td>Data</td>

          <td>
            ```json theme={null}
            {
            "userId": "12345",
            "status": "active"
            }
            ```
          </td>
        </tr>
      </tbody>
    </table>

    Validates any JSON structure that contains the JSON object provided in the input field, for example:

    ```json theme={null}
    {
    "userId": "12345", // part of the provided JSON object
    "status": "active", // part of the provided JSON object
    "timestamp": "2024-01-01T10:00:00Z" // not part of the provided JSON object
    }
    ```

    Fails if the JSON structure doesn't contain the JSON object provided in the input field, for example:

    ```json theme={null}
    {
    "userId": "12345", // subset of the provided JSON object
    "status": "failed", // not part of the provided JSON object
    "timestamp": "2024-01-01T10:00:00Z" // not part of the provided JSON object
    }
    ```
  </Accordion>

  <Accordion title="Inverted Assertion">
    In this example, configure the assertion as follows:

    <table>
      <thead>
        <tr>
          <th>Parameter</th>
          <th>Value</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Invert assertion</td>
          <td>Activated</td>
        </tr>

        <tr>
          <td>Use partial comparison</td>
          <td>Activated</td>
        </tr>

        <tr>
          <td>Data</td>

          <td>
            ```json theme={null}
            {
            "status": "failed"
            }
            ```
          </td>
        </tr>
      </tbody>
    </table>

    Validates any JSON structure that doesn't contain the JSON object provided in the input field, for example:

    ```json theme={null}
    {
    "userId": "12345",
    "status": "active", // validates if status isn't failed
    "timestamp": "2024-01-01T10:00:00Z"
    }
    ```
  </Accordion>
</AccordionGroup>

### Intent Assertion

Validates that the [Intent](/ai/platform-features/nlu/intents/overview) provided in the input field has been recognized in the user input.

| Parameter        | Type        | Description                                                                           |
| ---------------- | ----------- | ------------------------------------------------------------------------------------- |
| Invert assertion | Option      | Sets the assertion to validate the absence of the Intent provided in the input field. |
| Intent           | Input field | Sets the Intent name to validate.                                                     |

#### Examples

<AccordionGroup>
  <Accordion title="Exact Match">
    In this example, configure the assertion as follows:

    | Parameter        | Value           |
    | ---------------- | --------------- |
    | Invert assertion | Deactivated     |
    | Intent           | `"greet.hello"` |

    Validates only that the `"greet.hello"` Intent has been recognized.
  </Accordion>

  <Accordion title="Inverted Match">
    In this example, configure the assertion as follows:

    | Parameter        | Value            |
    | ---------------- | ---------------- |
    | Invert assertion | Activated        |
    | Intent           | `"cancel.order"` |

    Validates that the `"cancel.order"` Intent hasn't been recognized.
  </Accordion>
</AccordionGroup>

### Slot Assertion

Validates that the [Slot](/ai/platform-features/nlu/slots/overview) provided in the input field has been recognized in the user input.

| Parameter        | Type        | Description                                                                         |
| ---------------- | ----------- | ----------------------------------------------------------------------------------- |
| Invert assertion | Option      | Sets the assertion to validate the absence of the Slot provided in the input field. |
| Slot             | Input field | Sets the Slot name to validate.                                                     |

#### Examples

<AccordionGroup>
  <Accordion title="Exact Match">
    In this example, configure the assertion as follows:

    | Parameter        | Value       |
    | ---------------- | ----------- |
    | Invert assertion | Deactivated |
    | Slot             | `username`  |

    Validates only that the `username` Slot has been recognized.
  </Accordion>

  <Accordion title="Inverted Assertion">
    In this example, configure the assertion as follows:

    | Parameter        | Value      |
    | ---------------- | ---------- |
    | Invert assertion | Activated  |
    | Slot             | `password` |

    Validates that the `password` Slot hasn't been recognized.
  </Accordion>
</AccordionGroup>

### Context Assertion

Validates the data in the [Context object](/ai/agents/develop/ai-agent-memory/context) against the data provided in the input field.

| Parameter              | Type        | Description                                                                                |
| ---------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| Invert assertion       | Option      | Sets the assertion to validate the absence of the context data provided in the input field |
| Use partial comparison | Option      | Allows matches of a subset of the context data to validate.                                |
| Context data           | Input field | Sets the context data to validate in JSON format.                                          |

#### Examples

<AccordionGroup>
  <Accordion title="Exact Match">
    In this example, configure the assertion as follows:

    <table>
      <thead>
        <tr>
          <th>Parameter</th>
          <th>Value</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Invert assertion</td>
          <td>Deactivated</td>
        </tr>

        <tr>
          <td>Use partial comparison</td>
          <td>Deactivated</td>
        </tr>

        <tr>
          <td>Context data</td>

          <td>
            ```json theme={null}
            {
            "authenticated": true,
            "userRole": "premium",
            "sessionId": "abc123"
            }
            ```
          </td>
        </tr>
      </tbody>
    </table>

    Validates only the exact JSON object provided in the input field.
  </Accordion>

  <Accordion title="Partial Match">
    In this example, configure the assertion as follows:

    <table>
      <thead>
        <tr>
          <th>Parameter</th>
          <th>Value</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Invert assertion</td>
          <td>Deactivated</td>
        </tr>

        <tr>
          <td>Use partial comparison</td>
          <td>Activated</td>
        </tr>

        <tr>
          <td>Context data</td>

          <td>
            ```json theme={null}
            {
            "hasCreditCard": true,
            "activeCreditCard": true
            }
            ```
          </td>
        </tr>
      </tbody>
    </table>

    Validates any context data that contains the JSON object provided in the input field, for example:

    ```json theme={null}
    {
    "hasCreditCard": true, // part of the provided JSON object
    "activeCreditCard": true, // part of the provided JSON object
    "sessionId": "abc123" // not part of the provided JSON object
    }
    ```

    Fails if the JSON structure doesn't contain the JSON object provided in the input field, for example:

    ```json theme={null}
    {
    "hasCreditCard": true, // subset of the provided JSON object
    "activeCreditCard": false, // not part of the provided JSON object
    "sessionId": "abc123" // not part of the provided JSON object
    }
    ```
  </Accordion>

  <Accordion title="Inverted Assertion">
    In this example, configure the assertion as follows:

    <table>
      <thead>
        <tr>
          <th>Parameter</th>
          <th>Value</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Invert assertion</td>
          <td>Activated</td>
        </tr>

        <tr>
          <td>Use partial comparison</td>
          <td>Activated</td>
        </tr>

        <tr>
          <td>Context data</td>

          <td>
            ```json theme={null}
            {
            "activeCreditCard": false
            }
            ```
          </td>
        </tr>
      </tbody>
    </table>

    Validates any JSON structure that doesn't contain the JSON object provided in the input field, for example:

    ```json theme={null}
    {
    "hasCreditCard": true,
    "activeCreditCard": true, // validates if activeCreditCard isn't false
    "creditCardNumber": "1234567890"
    }
    ```
  </Accordion>
</AccordionGroup>

### State Assertion

Validates the conversation state.

| Parameter        | Type        | Description                                                                          |
| ---------------- | ----------- | ------------------------------------------------------------------------------------ |
| Invert assertion | Option      | Sets the assertion to validate the absence of the State provided in the input field. |
| State            | Input field | Sets the State name to validate.                                                     |

#### Examples

<AccordionGroup>
  <Accordion title="Exact Match">
    In this example, configure the assertion as follows:

    | Parameter        | Value               |
    | ---------------- | ------------------- |
    | Invert assertion | Deactivated         |
    | State            | `waiting_for_input` |

    Validates only that the `waiting_for_input` State is active.
  </Accordion>

  <Accordion title="Inverted Assertion">
    In this example, configure the assertion as follows:

    | Parameter        | Value         |
    | ---------------- | ------------- |
    | Invert assertion | Activated     |
    | State            | `error_state` |

    Validates only that the `error_state` State isn't active.
  </Accordion>
</AccordionGroup>

## Best Practices

For testing best practices, see [Best Practices: Testing your Virtual Agents with Playbooks](https://support.cognigy.com/hc/en-us/articles/9585431937948-Best-Practices-Testing-your-Virtual-Agents-with-Playbooks#7-regression-test-nlu-models-0-6).

## More Information

* [Slots](/ai/platform-features/nlu/slots/overview)
* [Intents](/ai/platform-features/nlu/intents/overview)