# Intents

An **Intent** is a named NLP trigger for an Agent. When a user message semantically matches the intent's phrases, the conversation branches into the flow node wired to that intent.

Intents are *agent-scoped*. They live under one [Agent](/docs/concepts/agents) and are referenced by `TRIGGER_INTENT` nodes inside that agent's [Flows](/docs/concepts/flows).

## Identity

| Field | Type | Notes |
|  --- | --- | --- |
| `id` | number | Use as `intentId`. |
| `name` | string | Human-readable label (e.g. `cancellation`, `pricing_question`). |
| `description` | string? |  |
| `status` | enum | `ACTIVE` · `INACTIVE` · `ARCHIVED`. |
| `assistantId` | string | Owning agent (UUID). |
| `flowId` | number? | Flow currently consuming this intent via a `TRIGGER_INTENT` node, if any. |
| `phrases` | array | List of training phrases (see below). |
| `createdAt` | string | ISO timestamp. |
| `updatedAt` | string | ISO timestamp. |


### Phrases

Each entry in `phrases` is `{ id: number, phrase: string }`.

- On **create**, send an array of plain strings.
- On **update**, you can mix entries with `id` (to keep/edit) and without `id` (to add new ones). Missing IDs are deleted.
- At least one phrase is required.


## Lifecycle


```
created → ACTIVE  ←→  INACTIVE  →  ARCHIVED
```

An `INACTIVE` intent is preserved but stops matching incoming messages.

## Generating training data

You don't have to write all phrases by hand. The API can suggest phrasings for you:


```http
POST /public/v1/agents/{agentId}/intents/generate-phrases
```

Body:


```json
{
    "name": "cancellation",
    "samples": ["cancel order", "I want to cancel my subscription"],
    "amount": 5
}
```

`amount` is bounded to **1–50**. The response returns suggested phrases that you can then send back via the create/update endpoints.

## Operations

| Verb | Path |
|  --- | --- |
| `GET` | `/public/v1/agents/{agentId}/intents` |
| `POST` | `/public/v1/agents/{agentId}/intents` |
| `GET` | `/public/v1/agents/{agentId}/intents/all` |
| `GET` | `/public/v1/agents/{agentId}/intents/{intentId}` |
| `PUT` | `/public/v1/agents/{agentId}/intents/{intentId}` |
| `DELETE` | `/public/v1/agents/{agentId}/intents/{intentId}` |
| `POST` | `/public/v1/agents/{agentId}/intents/generate-phrases` |


The `list` endpoint paginates; `all` returns the full set in one call. Both accept a `filterText` query.

## CLI


```bash
frontline agents intents list --table
frontline agents intents create --name cancellation --phrases '["cancel order","stop subscription"]'
frontline agents intents generate-phrases --name cancellation --samples '["cancel order"]' --amount 5
```