Intents and topics
MarkdownIntent sets used by semantic choices and the topic catalog used to detect a change of subject.
intent_set_get
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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). |