Skip to main content
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, el servidor MCP y la 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). 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».
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.

​
Un flujo mínimo

Calificar a quien llama, agendar si quiere y despedirse:
Cada campo, cada condición y cada regla están en el esquema Flow de la referencia de la API.

​
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.

​
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.
  • "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: