What are behaviors?

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.
`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:

{
  "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:

{
  "behaviors": ["preset:service-churn"]
}

Or with a full BehaviorDef for custom or adapted language:

{
  "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

Using behaviors

How to retrieve the preset catalog and include behaviors in your requests.

Custom behaviors

Define your own behaviors from scratch or adapted from pre-built ones.

Best practices

Write descriptions that produce consistent, accurate detections.

Velma Triage

Behaviors

Detection packages

What are behaviors?

Two ways to use behaviors

The BehaviorDef schema

What Velma returns

A minimal example

Next steps

Using behaviors

Custom behaviors

Best practices

​Two ways to use behaviors

​The BehaviorDef schema

​What Velma returns

​A minimal example

​Next steps

Using behaviors

Custom behaviors

Best practices

Two ways to use behaviors

The BehaviorDef schema

What Velma returns

A minimal example

Next steps