Saltar a la navegación
ConfigurarComportamiento del agenteProcedimientos

Procedimientos estructurados

Una secuencia fija de pasos tipados que tu agente ejecuta siempre de la misma forma

Descripción general

Un procedimiento estructurado es un procedimiento que ejecuta una secuencia fija de pasos. Un procedimiento de formato libre ofrece indicaciones en lenguaje natural que el agente interpreta y adapta a la situación. Un procedimiento estructurado es una lista ordenada de pasos tipados que el agente ejecuta en orden cada vez que se aplica el procedimiento.

Usa un procedimiento estructurado cuando determinados pasos deban ocurrir siempre de la misma forma en cada llamada: verificar la identidad de quien llama, escalar un ticket o aceptar un pago. Lo creas como una lista breve de pasos en lenguaje sencillo.

Como todos los procedimientos, un procedimiento estructurado tiene un activador que describe cuándo se aplica. Cuando una conversación coincide con el activador, el agente ejecuta los pasos del procedimiento en orden y, después, vuelve al resto de la conversación.

Editor de procedimientos estructurados

Cuándo usar un procedimiento estructurado

Usa un procedimiento estructurado cuando determinados pasos deban ejecutarse siempre de la misma forma, pero aun así quieras crearlo rápidamente con pasos sencillos. Los procedimientos estructurados son más fáciles de escribir que un workflow, pero menos flexibles. Para saber cómo se comparan con los procedimientos de formato libre, los workflows y el prompt del sistema, consulta Cuándo usar procedimientos.

Anatomía de un procedimiento estructurado

Un procedimiento estructurado tiene tres partes: un nombre, un activador y una lista ordenada de pasos.

Nombre

Una etiqueta breve que identifica el procedimiento en el panel. El nombre nunca se envía al LLM, por lo que no afecta al comportamiento del agente.

Activador

Una descripción en lenguaje natural de cuándo debe ejecutar el agente este procedimiento, por ejemplo, Cuando el usuario pide reembolsar un pedido. El agente compara la intención del usuario con el activador de cada procedimiento y ejecuta el que coincide, así que los activadores deben ser concretos y distintos. El agente solo ve el texto del activador, nunca el nombre ni el ID del procedimiento. Un activador funciona igual que en cualquier procedimiento; consulta Redactar activadores.

Deja el activador vacío para convertir el procedimiento en un subprocedimiento que solo se ejecuta cuando otro procedimiento lo llama.

Pasos

El cuerpo del procedimiento es una lista ordenada de pasos con tipos definidos. Hay varios tipos de pasos y puedes combinarlos para describir la tarea.

PasoQué hace
AskPide información al usuario y espera. Sigue preguntando hasta que el usuario responde. Es el único paso que se pausa para el usuario.
TellHace que el agente comunique algo con sus propias palabras y pasa al siguiente paso.
SayHace que el agente diga un mensaje exacto palabra por palabra y pasa al siguiente paso. Un paso Say puede incluir una traducción configurada específicamente para cada idioma que admita el agente.
ToolLlama a una herramienta concreta. Puedes indicar al LLM en lenguaje natural cómo llamar a la herramienta o fijar explícitamente valores de parámetros cuando se requiera la máxima determinación. También puedes definir pasos para ejecutar si falla la llamada a la herramienta.
IfEvalúa una o varias condiciones en orden y ejecuta los pasos de la primera coincidencia. Se ejecuta un Else opcional cuando no hay ninguna coincidencia.
Sub-procedureEjecuta otro procedimiento estructurado. Cuando se completan sus pasos, el control vuelve al siguiente paso de este procedimiento (el que realiza la llamada).
System toolRealiza una acción integrada del sistema. Actualmente, solo se admite finalizar la llamada.
RetryVuelve a ejecutar el controlador de fallos de un paso Tool, incluida la llamada a la herramienta, hasta tres veces. Solo está disponible dentro del controlador de fallos de un paso Tool.

Menú de tipos de pasos de procedimientos estructurados

No todos los pasos pueden aparecer en cualquier lugar. Dentro de una rama If, puedes usar cualquier paso excepto otro If o un Retry. Dentro del controlador de fallos de un paso Tool, puedes usar cualquier paso excepto un If u otro Tool.

Referencia de pasos de la API

El content de un procedimiento estructurado es un documento codificado en JSON que contiene una matriz steps. Cada paso es un objeto identificado por su type. El activador es un campo independiente de nivel superior en el procedimiento, no forma parte de content. Las cargas útiles de la API y el SDK usan type: "deterministic" para el propio procedimiento.

Ask

Un paso Ask indica al agente que solicite información y espere hasta que el usuario proporcione una respuesta adecuada.

  • Tipo de API: ask
  • instruction: Cadena obligatoria y no vacía.
{
  "type": "ask",
  "instruction": "Ask the user for their order ID."
}

Tell

Un paso Tell indica al agente que genere un único mensaje con sus propias palabras. No espera una respuesta del usuario antes de continuar.

  • Tipo de API: tell
  • instruction: Cadena obligatoria y no vacía.
{
  "type": "tell",
  "instruction": "Explain that the refund normally takes five to ten business days."
}

Say

Un paso Say reproduce el texto proporcionado exactamente como está escrito y después continúa. Proporciona message_translations para dar al agente un mensaje exacto para cada idioma adicional que admita, con la clave del código de idioma.

  • Tipo de API: say
  • message: Cadena obligatoria y no vacía.
  • message_translations: Objeto opcional que asigna un código de idioma a { "value": "..." }.
{
  "type": "say",
  "message": "Your refund has been submitted.",
  "message_translations": {
    "es": { "value": "Su reembolso ha sido enviado." }
  }
}

If, else if y else

Un paso If contiene una o varias ramas condicionales ordenadas. Se ejecuta la primera rama que coincide. La matriz opcional fallback es la rama Else.

  • Tipo de API: branch
  • branches: Lista obligatoria y no vacía de ramas condicionales.
  • fallback: Lista opcional de pasos Else.
  • Cada rama requiere una condition y una lista steps no vacía.
{
  "type": "branch",
  "branches": [
    {
      "condition": {
        "type": "llm",
        "condition": "The user is on an annual plan."
      },
      "steps": [
        {
          "type": "say",
          "message": "Your annual plan is eligible for a prorated refund."
        }
      ]
    }
  ],
  "fallback": [
    {
      "type": "tell",
      "instruction": "Explain that the account's plan could not be determined."
    }
  ]
}

Esto se comporta como if/else-if/else:

  1. Las condiciones se evalúan en orden.
  2. Se ejecuta la primera rama que coincide.
  3. Si no coincide ninguna condición, se ejecuta fallback.
  4. Cuando termina una rama, el procedimiento vuelve a unirse a la secuencia principal.

El ejemplo anterior usa una condición de texto, que el modelo evalúa en lenguaje natural. Las condiciones también pueden ser expresiones sobre variables dinámicas:

{
  "type": "expression",
  "expression": {
    "type": "eq_operator",
    "left": {
      "type": "dynamic_variable",
      "name": "plan_tier"
    },
    "right": {
      "type": "string_literal",
      "value": "annual"
    }
  }
}

Una condición de expresión comprueba variables dinámicas, que se rellenan con los resultados de herramientas o se establecen al iniciar la conversación. No puede leer la respuesta más reciente del usuario. Para ramificar según lo que haya dicho el usuario, usa una condición de texto.

Todas las ramas de un mismo paso If deben usar el mismo tipo de condición: llm o expression.

Tool

Un paso Tool llama a una herramienta concreta.

  • Tipo de API: tool_call
  • tool_id: ID de herramienta obligatorio y no vacío. La herramienta debe estar vinculada al agente.
  • tool_name: Nombre de herramienta obligatorio que debe coincidir con la herramienta.
  • instruction: Instrucción opcional que describe cómo llamar a la herramienta.
  • schema_overrides: Valores fijos opcionales para los parámetros de la herramienta.
  • on_failure: Controlador de fallos opcional.
{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "instruction": "Look up the order using the order ID provided by the user."
}

Valores fijos de parámetros

Usa schema_overrides cuando un parámetro deba tener siempre un valor específico. El modelo no ve ni elige un parámetro sobrescrito. Las claves son rutas de parámetros en el esquema de la herramienta; cada valor indica una fuente:

sourceCamposComportamiento
constantconstant_valueEnvía siempre el valor indicado.
dynamic_variabledynamic_variableEnvía el valor actual de la variable dinámica indicada.
llmprompt (opcional)Permite que el modelo elija el valor, con una anulación de prompt opcional.
omitOmite el parámetro de la llamada.
{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "update_ticket",
  "schema_overrides": {
    "request_body.status": { "source": "constant", "constant_value": "pending" },
    "request_body.ticket_id": { "source": "dynamic_variable", "dynamic_variable": "ticket_id" }
  }
}

Gestión de fallos

Sin on_failure, una llamada a una herramienta que falla finaliza la conversación. Añade on_failure para ejecutar en su lugar pasos de recuperación.

  • fallback: Lista obligatoria y no vacía de pasos que se ejecutan cuando falla la herramienta.
  • branches: Reservado para la gestión condicional de fallos. Déjalo vacío.
{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "on_failure": {
    "branches": [],
    "fallback": [
      {
        "type": "tell",
        "instruction": "Explain that the order could not be retrieved and offer to connect the user with support."
      }
    ]
  }
}

Un controlador de fallos puede contener pasos Ask, Tell, Say, Sub-procedure, System tool y Retry. No puede contener pasos Tool ni If. Después de ejecutar el controlador, el procedimiento continúa con el paso posterior al paso Tool.

Retry

Un paso Retry vuelve a ejecutar el controlador de fallos que lo contiene, incluida la llamada a la herramienta. Cada intento vuelve a llamar a la herramienta y, si vuelve a fallar, ejecuta de nuevo todos los pasos del controlador. Cuando se agotan los intentos, la conversación termina.

  • Tipo de API: retry
  • max_retries: Entero opcional de 1 a 3. El valor predeterminado es 1.
  • El valor cuenta los intentos posteriores a la llamada original a la herramienta.
  • Retry solo es válido dentro de on_failure.
  • Retry debe ser el último paso de su controlador de fallos, ya que los pasos posteriores serían inaccesibles.
{
  "type": "retry",
  "max_retries": 2
}

Sub-procedure

Un paso Sub-procedure ejecuta otro procedimiento estructurado. Cuando se completan los pasos de ese procedimiento, la ejecución vuelve al paso posterior al paso Sub-procedure.

  • Tipo de API: sub_procedure
  • procedure_id: ID de procedimiento obligatorio y no vacío.
  • El destino debe existir en el mismo agente.
  • El destino debe ser un procedimiento estructurado.
  • Un procedimiento no puede invocarse a sí mismo.
{
  "type": "sub_procedure",
  "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3"
}

System tool

Un paso System tool realiza una acción integrada del sistema.

  • Tipo de API: system_tool
  • system_tool_name: Nombre de herramienta del sistema obligatorio.
  • Actualmente, solo se admite end_call. Es posible que se añadan más herramientas del sistema más adelante.
  • Como end_call es terminal, debe ser el último paso de la secuencia, rama o controlador de fallos que lo contiene.
{
  "type": "system_tool",
  "system_tool_name": "end_call"
}

Reglas de validación

Al publicar el agente o guardar el borrador del agente, se rechaza cualquier procedimiento estructurado que incumpla alguna de estas reglas. El error identifica el paso problemático mediante su ruta.

  • No se pueden colocar dos pasos If consecutivos.
  • Los pasos If no se pueden anidar.
  • Un paso If con condiciones de expresión no puede seguir directamente a un paso Ask.
  • Todas las condiciones de un mismo paso If deben ser del mismo tipo: llm o expression.
  • Retry solo puede aparecer dentro de on_failure y debe ser el último paso allí.
  • end_call debe ser el último paso de la lista en la que aparezca.
  • El fallback de un controlador de fallos debe contener al menos un paso.
  • Un Sub-procedure debe apuntar a un procedimiento estructurado existente en el mismo agente y no a sí mismo.
  • tool_id debe ser una herramienta del agente, tool_name debe coincidir y schema_overrides debe coincidir con el esquema de la herramienta.
  • La lista steps, cada instruction y cada message no pueden estar vacíos.

Para saber cómo reestructurar un procedimiento que incumple una de estas reglas, consulta Buenas prácticas.

Ejemplo completo de API

Este ejemplo gestiona la cancelación de un pedido según el estado del envío. Fija un parámetro de herramienta, se recupera de una llamada a una herramienta fallida, invoca otro procedimiento estructurado y luego finaliza la llamada.

{
  "steps": [
    {
      "type": "ask",
      "instruction": "Ask the user for their order ID."
    },
    {
      "type": "branch",
      "branches": [
        {
          "condition": {
            "type": "llm",
            "condition": "The user says the order has already shipped."
          },
          "steps": [
            {
              "type": "tell",
              "instruction": "Explain that shipped orders must be returned before they can be refunded."
            }
          ]
        },
        {
          "condition": {
            "type": "llm",
            "condition": "The user says the order has not shipped."
          },
          "steps": [
            {
              "type": "tool_call",
              "tool_id": "tool_abc123",
              "tool_name": "cancel_order",
              "instruction": "Cancel the order using the order ID provided by the user.",
              "schema_overrides": {
                "request_body.notify_customer": { "source": "constant", "constant_value": true }
              },
              "on_failure": {
                "branches": [],
                "fallback": [
                  {
                    "type": "tell",
                    "instruction": "Apologize that the cancellation did not go through and say you will try once more."
                  },
                  {
                    "type": "retry",
                    "max_retries": 1
                  }
                ]
              }
            }
          ]
        }
      ],
      "fallback": [
        {
          "type": "ask",
          "instruction": "Ask whether the order has already shipped."
        }
      ]
    },
    {
      "type": "sub_procedure",
      "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3"
    },
    {
      "type": "say",
      "message": "Thank you for contacting us. Goodbye.",
      "message_translations": {
        "es": { "value": "Gracias por contactarnos. Adiós." }
      }
    },
    {
      "type": "system_tool",
      "system_tool_name": "end_call"
    }
  ]
}

Cómo se ejecuta un procedimiento estructurado

Convertir los pasos de un procedimiento estructurado al formato que ejecuta el agente se denomina compilación. La plataforma compila todos los procedimientos estructurados al publicar; no tienes que compilar nada tú. Actualmente, el resultado compilado se muestra como nodos de solo lectura en la pestaña Workflow.

Cuando la solicitud del usuario coincide con el activador de un procedimiento, el agente entra en el procedimiento y ejecuta sus pasos en orden. Mientras está dentro del procedimiento estructurado, el agente se centra en cada paso de forma aislada. Cuando llega al final, vuelve al resto de la conversación.

Las siguientes reglas describen cómo se comportan los pasos en tiempo de ejecución.

Todos los pasos excepto Ask se ejecutan inmediatamente y el control pasa al siguiente paso dentro del mismo turno. Un paso Tell o Say transmite su mensaje y continúa. No hay ningún paso que pause la conversación aparte de Ask, ni ningún paso que finalice el turno actual. Si necesitas que el usuario introduzca información, usa un paso Ask. Si la conversación debe terminar, usa la herramienta del sistema end_call.

Cuando se completa el último paso, el procedimiento termina y el agente vuelve al resto de la conversación con el turno todavía abierto, por lo que puede decir algo más. Cuando se completa un subprocedimiento, el control vuelve al siguiente paso del procedimiento que lo llamó.

Un paso Tool no puede ramificarse según un código de estado ni el cuerpo de la respuesta. Si la herramienta tiene éxito, el procedimiento continúa. Si falla y el paso no tiene un controlador de fallos, la conversación termina. Si tiene uno, se ejecutan los pasos del controlador y el procedimiento continúa con el siguiente paso. Un Retry dentro del controlador vuelve a ejecutar la herramienta y, si vuelve a fallar, todos los pasos del controlador, hasta que la herramienta tenga éxito o se agoten los intentos. Si se agotan, la conversación termina.

Las condiciones se evalúan en orden y se ejecuta la primera coincidencia. La rama Else se ejecuta cuando no hay ninguna coincidencia. Si no hay Else y no coincide nada, el procedimiento continúa con el paso posterior al If. Un caso no gestionado no es un error.

Las decisiones tomadas dentro de una rama If no se recuerdan en los pasos posteriores. Si se necesita más adelante algo aprendido en una rama, persístelo explícitamente con una llamada a una herramienta o una variable dinámica.

Solo los pasos Tool pueden llamar a herramientas. No es necesario indicar a un paso Ask, Tell o Say que no llame a herramientas; no puede hacerlo.

Gestionar un procedimiento estructurado

Abre tu agente en el panel y selecciona Procedures. Usa + para crear un procedimiento estructurado. Añade un activador, selecciona un tipo para cada paso y publica los cambios del agente.

El panel valida los procedimientos estructurados mientras los editas. Si un procedimiento incumple una regla de validación, el botón Publish muestra un estado de error, la pestaña Procedures muestra una insignia de error y no se puede iniciar la vista previa hasta que se corrija el procedimiento. Selecciona el indicador de error para ver qué procedimiento y paso se ven afectados.

Editor de procedimientos estructurados con el botón Publish en estado de error y una insignia de 1 Error

Cuadro de diálogo con los detalles de validación que muestra el procedimiento fallido y el paso que necesita un mensaje

Buenas prácticas

Cada tipo de paso ya aplica su propio comportamiento, así que rara vez necesitas detallarlo. Escribe la intención de cada paso y deja que el tipo de paso se encargue del resto. Las indicaciones siguientes cubren los casos que conviene configurar bien.

Para probar un procedimiento estructurado, sigue Iterar en un procedimiento.

Elegir tipos de paso

Un paso Ask espera una respuesta. Si agrupas varias preguntas en una sola instrucción, el agente suele omitir algunas o combinarlas. Usa un Ask para cada dato.

Un paso Tell transmite su mensaje y continúa sin esperar. Un Tell formulado como pregunta nunca recibe respuesta. Si un paso necesita una respuesta del usuario, es un Ask.

Un paso Ask avanza cuando recibe una respuesta adecuada. Si no queda claro qué se considera una respuesta a partir de la pregunta, indícalo en la instrucción; por ejemplo: _Pide el ID del pedido; un ID válido tiene ocho dígitos _.

Usa un paso Tell cuando el agente deba redactar el mensaje por sí mismo y un paso Say cuando el texto deba ser literal o traducido. Ambos transmiten exactamente un mensaje, así que no hace falta indicar a un paso que envíe un único mensaje.

Los pasos Ask, Tell y Say no pueden llamar a herramientas. Escribir no llames a ninguna herramienta en ellos añade ruido a la instrucción sin cambiar el comportamiento.

Estructurar el procedimiento

No se pueden colocar dos pasos If seguidos. Insertar un Tell o Say sin relación entre ellos para cumplir la regla hace que el agente diga algo que no debería. En su lugar, incorpora la segunda decisión en el primer If como ramas Else if adicionales, o muévela a un subprocedimiento.

Los pasos If no se pueden anidar. Cuando una decisión depende de otra, incluye la decisión interna en su propio procedimiento estructurado y llámalo con un paso Sub-procedure desde la rama que lo necesite.

Un paso If sin Else continúa al siguiente paso cuando no coincide nada. Si el caso sin coincidencia debe comportarse de otra forma, añade una rama Else para él.

Las decisiones tomadas dentro de una rama If no se recuerdan después. Si un paso posterior depende de algo aprendido en una rama, regístralo con una llamada a herramienta o una variable dinámica dentro de la rama.

Las condiciones de expresión comprueban variables dinámicas. Coloca un paso If que las use justo después del paso Tool que establece esas variables. Para bifurcar según lo que haya dicho el usuario, usa una condición de texto.

Cuando varios procedimientos estructurados compartan la misma secuencia, como escalar a una persona, inclúyela en un procedimiento estructurado con un activador vacío y llámalo desde cada uno. Las secuencias copiadas acaban divergiendo con el tiempo.

Trabajar con herramientas

Un paso Tool siempre llama a su herramienta. Una condición escrita en la instrucción, como _omite esto si el ticket ya tiene una etiqueta _, no puede impedir la llamada. Si la llamada no debe producirse siempre, incluye la condición en un paso If antes del paso Tool.

Cuando un parámetro deba tener siempre un valor específico, establécelo con una anulación constant en schema_overrides. Una instrucción como establece siempre el estado como pendiente pide al modelo que la cumpla; una anulación se aplica obligatoriamente y no se puede omitir.

Sin on_failure, cualquier error de la herramienta termina la conversación. Añade un controlador que indique al usuario qué ha ocurrido y vuelva a intentarlo, escale el caso o continúe.

Un paso Tool solo ejecuta la herramienta; el agente no puede hablar ni tomar una decisión durante él. Para hablar con el usuario o bifurcar según lo que haya devuelto la herramienta, inclúyelo en un paso independiente antes o después del paso Tool.

Redactar instrucciones

El procedimiento controla qué se ejecuta después y el agente no conoce los pasos posteriores mientras ejecuta el actual. Deja que el orden de los pasos se encargue de la secuencia.

Las frases escritas en las instrucciones de los pasos, como este es el último mensaje de este turno, piden al agente que aplique un límite que la plataforma no admite. Usa un paso Ask para esperar al usuario o la herramienta del sistema end_call para finalizar la conversación.

El tono, el formato, las despedidas y las políticas de rechazo corresponden al prompt del sistema. La instrucción de un paso debe indicar solo lo específico de ese paso.

Combinar procedimientos

Las indicaciones generales para combinar procedimientos también se aplican a los procedimientos estructurados; consulta Combinar procedimientos en la página de procedimientos de formato libre.

Un patrón es específico de la combinación de tipos: un procedimiento de formato libre puede hacer referencia a uno estructurado. Mantén la gestión abierta en un procedimiento de formato libre y delega en un procedimiento estructurado las partes que deben ejecutarse siempre de la misma manera, como la verificación de identidad o la escalada.

Limitaciones

  • Los pasos If no se pueden anidar ni se pueden colocar dos pasos If seguidos.
  • La única herramienta del sistema compatible es end_call.
  • Los procedimientos estructurados no pueden hacer referencia a documentos de la base de conocimiento.
  • No hay forma de finalizar el turno actual cuando termina un procedimiento; el agente mantiene el turno abierto y puede seguir hablando.
  • No se puede iniciar un procedimiento estructurado desde un nodo específico del workflow en el panel.
  • Iniciar un procedimiento añade latencia: el agente realiza una llamada a herramienta para entrar en él y después avanza por el workflow generado.

Compatibilidad con proveedores de modelos

Los procedimientos estructurados fuerzan llamadas a herramientas internas al entrar en un subprocedimiento y al completar un procedimiento. Las principales familias de modelos de OpenAI, Anthropic, Gemini y Grok admiten la elección forzada de herramientas. Es posible que otros modelos o proveedores personalizados no la garanticen, lo que puede hacer menos fiables las transiciones entre subprocedimientos o la finalización de procedimientos. Verifica la compatibilidad con la elección forzada de herramientas cuando uses otro proveedor de modelos.

Consulta Procedimientos para conocer los límites que se aplican a todos los procedimientos, incluido el límite de tamaño del contenido y las diferencias entre procedimientos estructurados y de formato libre.