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

# What are behaviors?

> Behaviors are the signals you tell Velma to listen for. Each one is a named, described detection target that Velma evaluates against the conversation audio.

A behavior is a detection target — a named signal you want Velma to look for in a conversation. You include behaviors in your `BatchConfig` before streaming audio, and Velma emits a `behavior_detection` event for each one with a verdict, a confidence score, and the clips that served as evidence.

Behaviors are the primary mechanism for customizing what Velma pays attention to. The same underlying audio can be evaluated against a compliance checklist, a safety policy, a sales coaching rubric, or any other set of criteria — it all depends on the behaviors you define.

## Two ways to use behaviors

**Use a pre-built behavior.** Modulate maintains a catalog of behaviors covering common use cases across customer support, sales, content moderation, media monitoring, and more. Call `GET /api/velma-2-batch/list-presets` or `GET /api/velma-2-streaming/list-presets` to retrieve the catalog. Each entry includes an `identifier` you reference with the `"preset:<identifier>"` syntax in your `behaviors` array.

**Define a custom behavior.** Supply your own `BehaviorDef` with a name and description you write. Velma evaluates whatever criteria you specify. You can start from scratch or adapt a pre-built definition as a template.

Both paths use the same `BehaviorDef` object in your `BatchConfig`. The difference is whether the UUID and descriptions come from the preset catalog or from you.

## The BehaviorDef schema

Every behavior in your `BatchConfig.behaviors` array must include all four required fields:

| Field                                | Type        | Required | Description                                                                                                                                                     |
| ------------------------------------ | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `behavior_uuid`                      | UUID string | Yes      | Uniquely identifies this behavior. For pre-built behaviors, use the UUID from the list-presets response. For custom behaviors, supply a UUID v4 you generate.   |
| `name`                               | string      | Yes      | A short label. Used in `behavior_detection` event responses to identify which behavior fired.                                                                   |
| `short_description`                  | string      | Yes      | One sentence summarizing what the behavior detects.                                                                                                             |
| `detailed_description`               | string      | Yes      | The criteria Velma uses to determine whether the behavior is present. This is the most important field — see [Best practices](/velma/behaviors/best-practices). |
| `applies_to_conversation_type_uuids` | UUID array  | No       | Restrict this behavior to specific conversation types. Null or omitted means all types.                                                                         |
| `applies_to_participant_role_uuids`  | UUID array  | No       | Restrict this behavior to specific participant roles. Null or omitted means all roles.                                                                          |

## What Velma returns

Each behavior produces a `behavior_detection` event:

```json theme={null}
{
  "type": "behavior_detection",
  "detection": {
    "behavior_uuid": "33333333-3333-4333-8333-033333333006",
    "behavior_name": "Service Churn",
    "speaker_label": "Speaker_1",
    "detected": true,
    "confidence": 0.91,
    "evidence_clip_uuids": ["a1b2c3d4-...", "e5f6a7b8-..."],
    "definitive_clip_uuid": "a1b2c3d4-...",
    "reasoning": "Speaker explicitly stated they want to cancel their subscription."
  }
}
```

`detected` is the primary verdict. `evidence_clip_uuids` links the detection back to the specific clips in the session.

## A minimal example

Using a preset reference — the simplest path:

```json theme={null}
{
  "behaviors": ["preset:service-churn"]
}
```

Or with a full `BehaviorDef` for custom or adapted language:

```json theme={null}
{
  "behaviors": [
    {
      "behavior_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Service Churn",
      "short_description": "Customer decides to cancel an ongoing service.",
      "detailed_description": "To qualify, the speech must feature assertions that the speaker would like to cancel a service or subscription. The speech must not be phrased as a threat in the first or second person voice."
    }
  ]
}
```

## Next steps

<CardGroup cols={3}>
  <Card title="Using behaviors" icon="play" href="/velma/behaviors/using-behaviors">
    How to retrieve the preset catalog and include behaviors in your requests.
  </Card>

  <Card title="Custom behaviors" icon="pen-to-square" href="/velma/behaviors/custom-behaviors">
    Define your own behaviors from scratch or adapted from pre-built ones.
  </Card>

  <Card title="Best practices" icon="circle-check" href="/velma/behaviors/best-practices">
    Write descriptions that produce consistent, accurate detections.
  </Card>
</CardGroup>