# Intents and topics

> Intent sets used by semantic choices and the topic catalog used to detect a change of subject.

Intent sets used by semantic choices and the topic catalog used to detect a change of subject.

## `intent_set_get`

**Get an intent set** · Read only · Listed to the agent from the start

Gets an intent set by id: returns {intent_set_id, branches (dict branch_name -> info), branch_names (list)}. Useful to check that the branches of a node match the set.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `set_id` | string | Yes |  |

## `intent_sets_list`

**List intent sets** · Read only · Listed to the agent from the start

Lists all intent sets of the organization, grouped as set -> branch -> phrases and count. Use it to reuse an existing set before creating a new one.

No arguments.

## `intent_test`

**Test an intent set** · Read only · Listed to the agent from the start

Tests semantic routing: vectorizes `query` and searches it in the set. Returns {query, intent_set_id, matches:[{branch_name, score, phrase, phrase_id}], top_match}. It uses the same engine the virtual agent runs in production.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `intent_set_id` | string | Yes |  |
| `query` | string | Yes |  |
| `threshold` | number | No | Default: `0.0`. |
| `top_k` | integer | No | Default: `5`. |

## `intent_validate`

**Validate an intent set** · Read only · Listed to the agent from the start

Validates the quality of a set before publishing (simulation, read-only). For each branch: marks `weak` if it has fewer than `min_phrases` phrases, and `confusions` when a phrase of the branch matches another branch with score >= `threshold` (overlap). `ok=false` if any branch is weak or has confusions. Refine phrases with `intent_set_upsert_branch` and validate again.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `set_id` | string | Yes |  |
| `min_phrases` | integer | No | Default: `3`. |
| `threshold` | number | No | Default: `0.5`. |

## `topic_catalog_get`

**Get the topic catalog** · Read only · Listed to the agent from the start

Reads the customer's topic catalog (the list of topics used by the topic-change detector): returns `draft` (editable draft, with `updatedAt`) and `active` (active version, {version, topics}). With `list_versions=True` it lists the published versions; with `version=n` it reads that version. Read-only. Each topic is {id, name, criteria}: `id` is the value written in the flow's reason variable, `name` the visible name and `criteria` the short criterion the classifier receives. A published flow uses the catalog version it pinned at publish (`metaTopics`), not necessarily the active one.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Yes |  |
| `list_versions` | boolean | No | Default: `false`. |
| `version` | integer | No | Default: `0`. |

## `topic_catalog_propose`

**Propose a topic catalog** · Read only · Listed to the agent from the start

Proposes a topic catalog from a flow; it saves nothing. It takes the vocabulary of the reason capture (`settings.topicChange.motiveVar`, or `captured.motivo_contacto` if not configured) and the branches of the `choice` nodes that read that reason. Returns `topics` ([{id, name, criteria: ""}]), `source` (where each thing came from) and `notes`. `criteria` is left empty on purpose: it is a sentence saying when the customer is in that topic, to be written with the user and saved with `topic_catalog_save_draft`. The `id` values must be exactly what the flow's router understands. `source` = "draft" (default) | "active" (with `environment`).

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Yes |  |
| `flow_id` | string | Yes |  |
| `environment` | string | No | Default: `"prod"`. |
| `source` | string | No | Default: `"draft"`. |

## `flow_refreeze_topics`

**Update the topics of a flow** · Changes data · can overwrite or remove · Reached with `dakso_explore`

Updates a flow's topic catalog: publishes a new version of the flow with the same content as its active version in `environment` (and the same frozen modules) and the topic catalog pinned at its active version. It does not touch the draft nor activate. Without `apply` it returns a preview; with `apply=True` and `plan_hash` it publishes. The preview has the change (version pinned today -> catalog active), the `lint` and `planHash`; with `noChange` there is nothing to update. If something changed since the preview, apply refuses. Activating is a separate step (`flow_activate`).

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Yes |  |
| `flow_id` | string | Yes |  |
| `apply` | boolean | No | Default: `false`. |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
| `environment` | string | No | Default: `"prod"`. |
| `plan_hash` | string | No | Default: `""`. |

## `intent_branch_delete`

**Delete an intent branch** · Changes data · can overwrite or remove · Reached with `dakso_explore`

Deletes one branch of an intent set. Destructive action. For safety the agent does not run this action: the tool returns a link to the Dakso admin screen where a person confirms it. Give the user that link.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `branch_name` | string | Yes |  |
| `intent_set_id` | string | Yes |  |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |

## `intent_set_delete`

**Delete an intent set** · Changes data · can overwrite or remove · Reached with `dakso_explore`

Deletes a whole intent set. Destructive action. For safety the agent does not run this action: the tool returns a link to the Dakso admin screen where a person confirms it. Give the user that link.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `intent_set_id` | string | Yes |  |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |

## `intent_set_upsert_branch`

**Save an intent branch** · Changes data · can overwrite or remove · Reached with `dakso_explore`

Creates or updates a branch of a set with its training phrases and vectorizes them again. It REPLACES the branch's phrases. Names are sanitized (same as the admin) and limits are validated (up to 50 phrases, up to 200 characters each). Branches must exist in the set before wiring a `choice` node.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `branch_name` | string | Yes |  |
| `intent_set_id` | string | Yes |  |
| `phrases` | array | Yes |  |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |

## `topic_catalog_activate`

**Activate the topic catalog** · Changes data · can overwrite or remove · Reached with `dakso_explore`

Activates a published version of the topic catalog (also works as rollback: activate an earlier version). The catalog has a single active version, with no environments. The active one is used by testing, the draft preview and future publishes; prod keeps the version each flow pinned at publish until a `flow_refreeze_topics`.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Yes |  |
| `version` | integer | Yes |  |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |

## `topic_catalog_publish`

**Publish the topic catalog** · Changes data · can overwrite or remove · Reached with `dakso_explore`

Publishes the topic catalog draft as a new version (returns `version`). It does not activate it: that is `topic_catalog_activate`. Flows already published do not take the new version by themselves: each pinned a catalog version when published. Testing and the draft preview use the active one. To bring it to prod without republishing a flow use `flow_refreeze_topics` and then `flow_activate`.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Yes |  |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
| `notes` | string | No | Default: `""`. |

## `topic_catalog_save_draft`

**Save the topic catalog draft** · Changes data · can overwrite or remove · Reached with `dakso_explore`

Saves the draft of the topic catalog (replaces the whole `topics` list; does not publish). Each topic: {"id", "name", "criteria"}. `base_updated_at` = the `updatedAt` of the draft read with `topic_catalog_get`, so another person's changes are not overwritten (fails if it changed). Rules (the error has `details.errors`): 2 to 40 topics; `id` 1 to 60 characters (letters, digits, space, `_`, `-`), unique ignoring case and accents, never `sigue` (reserved); `name` 1 to 60; `criteria` 1 to 300. The `id` must be exactly the value the flow writes in the reason variable and its router understands. `topic_catalog_propose` builds a first proposal. Requires admin role or higher.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `client_id` | string | Yes |  |
| `topics` | array | Yes |  |
| `base_updated_at` | string | No | Default: `""`. |
| `descripcion` | string | No | One short sentence: what this call changes and why (10-200 chars, no personal data). |
