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

# Flujos: divide una conversación en etapas

> Qué es un flujo conversacional, cómo pasa el agente de una etapa a otra y cómo leer y cambiar un flujo desde la API, el servidor MCP y la CLI.

Un **flujo** divide una conversación en **etapas**. Cada etapa tiene sus propias instrucciones y sus propias tools, y el agente pasa de una a otra cuando se cumple una condición: el cliente quiere agendar, una tool respondió, una variable ya tiene valor. Un agente sin flujo funciona con un solo prompt, como siempre.

En el Constructor, la sección **Flujo** enseña el flujo como un lienzo. Todo lo que armas ahí también está disponible desde la [API pública](/es/api-reference), el [servidor MCP](/es/mcp/overview) y la [CLI](/es/guides/developers/cli), con las mismas reglas.

## Cómo funciona un flujo

Un flujo es un grafo: **nodos** (los pasos) unidos por **aristas** (las salidas de cada paso).

| Tipo de nodo | Qué hace |
| - | - |
| `prompt` | Una etapa de conversación: el agente habla con el cliente siguiendo el `prompt` de la etapa. |
| `say` | El agente dice el texto de `prompt` y sigue. |
| `tool` | Al entrar, corre todas las tools de `tool_ids`, sin que el modelo decida. |
| `set_variables` | Escribe valores en las variables del flujo. |
| `end` | Termina la conversación. |

La conversación empieza en `entry_node_id`. Al cerrar cada turno, las aristas del nodo actual se evalúan en este orden:

1. Las condiciones `tool_result` y `variable`, que no necesitan al modelo, por `priority` (la mayor primero).
2. Todas las condiciones `llm_decision`, en una sola llamada al modelo: el modelo elige la salida que corresponde, guiado por la `description` de cada una.
3. La arista `always`, que es el «si no» explícito.
4. Si nada aplica, la conversación se queda donde está.

A los **nodos globales** (`global_nodes`) se puede entrar desde cualquier etapa con su `global_condition`, y al terminar la conversación regresa a la etapa de la que venía. Sirven para «el cliente pide hablar con una persona» o «el cliente quiere cancelar».

<Warning>
  Una etapa de conversación (`prompt`) no puede tener una arista `always`. El agente saldría de la etapa en el primer turno en que el modelo no elija otra salida. Usa `llm_decision`, `tool_result` o `variable`. `always` sí va bien en los nodos `say`, `tool` y `set_variables`, que no esperan al cliente. Y al revés: una arista `llm_decision` sólo funciona desde una etapa `prompt`, porque los otros pasos no conversan y el modelo nunca elige.
</Warning>

## Un flujo mínimo

Calificar a quien llama, agendar si quiere y despedirse:

```json theme={null}
{
  "version": 2,
  "entry_node_id": "calificar",
  "nodes": [
    {
      "node_id": "calificar",
      "node_type": "prompt",
      "label": "Calificar",
      "prompt": "Averigua si quien llama quiere agendar una cita o tiene una pregunta.",
      "edges": [
        { "edge_id": "a_agendar", "to_node_id": "agendar", "condition": { "type": "llm_decision", "description": "Quiere agendar una cita" } },
        { "edge_id": "a_despedida", "to_node_id": "despedida", "condition": { "type": "llm_decision", "description": "Ya no tiene nada más que preguntar" } }
      ]
    },
    {
      "node_id": "agendar",
      "node_type": "prompt",
      "label": "Agendar",
      "prompt": "Pregunta el día y la hora que prefiere y confírmalos.",
      "edges": [
        { "edge_id": "agendada", "to_node_id": "despedida", "condition": { "type": "llm_decision", "description": "La cita quedó confirmada" } }
      ]
    },
    { "node_id": "despedida", "node_type": "end", "prompt": "" }
  ]
}
```

Cada campo, cada condición y cada regla están en el esquema `Flow` de la [referencia de la API](/es/api-reference).

## Leer el flujo

`GET /v1/agents/{id}` lo devuelve en `config.flow`, y `GET /v1/agents/{id}/versions/{version}` en `flow`. Vale `null` cuando el agente no tiene flujo.

```bash theme={null}
curl https://api.ryvo.so/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $RYVO_API_KEY"
```

## Cambiar el flujo

Manda el grafo **completo** en `flow` con `PATCH /v1/agents/{id}`. Reemplaza al actual: no hay forma de mandar un solo nodo, así que primero lee el flujo, cámbialo y devuélvelo entero.

```bash theme={null}
curl -X PATCH https://api.ryvo.so/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $RYVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "flow": { "version": 2, "entry_node_id": "calificar", "nodes": [ ... ] }, "expected_version": 4 }'
```

* `"flow": null` quita el flujo, y el agente vuelve a funcionar con su prompt.
* Como cualquier cambio de configuración, se guarda como una versión **borrador**. Publícala con `POST /v1/agents/{id}/publish` para que las llamadas la usen.
* Manda `expected_version` (el `current_version` que leíste) para no pisar un cambio que alguien hizo en el Constructor mientras tanto.

Si el grafo rompe una regla (una arista hacia un nodo que no existe, una arista `always` en una etapa, un `llm_decision` desde un paso que no conversa, una `description` en blanco, una tool que el agente no tiene), la respuesta es `400 invalid_flow` y **no se guarda nada**, ni el `name` ni el `status` que vengan en la misma petición. Un nodo sólo puede nombrar tools del agente: las nativas y las que la versión trae en `tool_ids`.

## Desde el servidor MCP y la CLI

* **MCP**: `get_agent` devuelve el flujo y `update_agent` acepta `flow` con las mismas reglas. Tu cliente de IA puede leer el flujo, cambiarlo y devolverlo entero.
* **CLI**: `ryvo agents get <id>` enseña una línea `flow` con el número de nodos y la etapa de entrada; agrega `--json` para ver el grafo completo. Para cambiarlo, pasa el cuerpo con `--data`:

```bash theme={null}
ryvo agents get $AGENT_ID --json > agente.json
# edita config.flow y guárdalo como flujo.json: { "flow": { ... } }
ryvo agents update $AGENT_ID --data @flujo.json
ryvo agents publish $AGENT_ID
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.