Procedimientos estructurados

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 realizarse de la misma forma en cada llamada: verificar la identidad de quien llama, escalar un ticket o procesar un pago. Lo creas como una breve lista 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 luego vuelve al resto de la conversación.

Cuándo usar un procedimiento estructurado

Usa un procedimiento estructurado cuando determinados pasos deban ejecutarse siempre de la misma forma, pero quieras crearlo rápidamente con pasos sencillos. Los procedimientos estructurados son más fáciles de escribir que un workflow, pero menos expresivos. 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 de control. El nombre nunca se envía al LLM, por lo que no afecta al comportamiento del agente.

Activador

Una descripción en lenguaje sencillo 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, por lo que los activadores deben ser concretos y diferenciados. 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 Escribir 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 tipados. Hay varios tipos de pasos, que puedes combinar para describir la tarea.

No todos los pasos pueden aparecer en cualquier lugar. Dentro de una rama Si, puedes usar cualquier paso excepto otro Si o un Reintentar. Dentro del controlador de errores de un paso Herramienta, puedes usar cualquier paso excepto un Si u otra Herramienta.

Referencia de pasos de la API

El content de un procedimiento estructurado es un documento codificado en JSON que contiene un array 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 procedimiento en sí.

Preguntar

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

• Tipo de API: ask
• instruction: Cadena obligatoria no vacía.

{
  "type": "ask",
  "instruction": "Ask the user for their order ID."
}

Contar

Un paso Contar 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 no vacía.

{
  "type": "tell",
  "instruction": "Explain that the refund normally takes five to ten business days."
}

Decir

Un paso Decir pronuncia el texto proporcionado exactamente como está escrito y luego continúa. Proporciona message_translations para dar al agente un mensaje exacto para cada idioma adicional que admita, identificado mediante el código de idioma.

• Tipo de API: say
• message: Cadena obligatoria 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." }
  }
}

Si, si no si y si no

Un paso Si contiene una o más ramas condicionales ordenadas. Se ejecuta la primera rama que coincide. El array fallback opcional es la rama Si no.

• Tipo de API: branch
• branches: Lista obligatoria no vacía de ramas condicionales.
• fallback: Lista opcional de pasos Si no.
• 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 funciona 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. Tras terminar 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 resultados de herramientas o se establecen al iniciar la conversación. No puede leer la respuesta más reciente del usuario. Para crear una rama según lo que haya dicho el usuario, usa una condición de texto.

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

Herramienta

Un paso Herramienta llama a una herramienta específica.

• Tipo de API: tool_call
• tool_id: ID de herramienta obligatorio no vacío. La herramienta debe estar vinculada al agente.
• tool_name: Nombre de herramienta obligatorio que coincide 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 errores 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 de parámetros fijos

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:

{
  "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 errores

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

• fallback: Lista obligatoria no vacía de pasos que se ejecutan cuando falla la herramienta.
• branches: Reservado para la gestión condicional de errores. 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 errores puede contener pasos Preguntar, Contar, Decir, Subprocedimiento, Herramienta del sistema y Reintentar. No puede contener pasos Herramienta ni Si. Después de ejecutar el controlador, el procedimiento continúa con el paso posterior al paso Herramienta.

Reintentar

Un paso Reintentar vuelve a ejecutar el controlador de errores 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, finaliza la conversación.

• 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.
• Reintentar solo es válido dentro de on_failure.
• Reintentar debe ser el paso final de su controlador de errores porque los pasos posteriores no serían accesibles.

{
  "type": "retry",
  "max_retries": 2
}

Subprocedimiento

Un paso Subprocedimiento ejecuta otro procedimiento estructurado. Cuando terminan los pasos de ese procedimiento, la ejecución vuelve al paso posterior al paso Subprocedimiento.

• Tipo de API: sub_procedure
• procedure_id: ID de procedimiento obligatorio 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"
}

Herramienta del sistema

Un paso Herramienta del sistema 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 paso final de la secuencia, rama o controlador de errores que lo contiene.

{
  "type": "system_tool",
  "system_tool_name": "end_call"
}

Reglas de validación

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

• No se pueden colocar dos pasos Si seguidos.
• Los pasos Si no pueden anidarse.
• Un paso Si con condiciones de expresión no puede seguir directamente a un paso Preguntar.
• Todas las condiciones de un mismo paso Si deben ser del mismo tipo: llm o expression.
• Reintentar solo puede aparecer dentro de on_failure y debe ser el último paso allí.
• end_call debe ser el último paso de cualquier lista en la que aparezca.
• El fallback de un controlador de errores debe contener al menos un paso.
• Un Subprocedimiento 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 herramienta fallida, invoca otro procedimiento estructurado y después 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 a la forma que ejecuta el agente se llama compilación. La plataforma compila todos los procedimientos estructurados al guardar el borrador del agente o publicar el agente; los autores nunca tienen que compilar nada por su cuenta.

Cuando la solicitud del usuario coincide con el activador de un procedimiento, la plataforma 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, la plataforma devuelve el control al resto de la conversación.

Las conexiones de workflow no pueden conectarse a un procedimiento estructurado ni salir de él. Usa un paso Subprocedimiento para encadenar procedimientos estructurados. La plataforma gestiona la entrada desde un activador coincidente y la finalización, incluido el retorno del control al nodo del workflow donde comenzó el procedimiento.

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

Gestionar un procedimiento estructurado

Buenas prácticas

Cada tipo de paso ya aplica su propio comportamiento, así que rara vez necesitas especificarlo. Describe 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 definir bien.

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

Elegir tipos de paso

Estructurar el procedimiento

Trabajar con herramientas

Redactar instrucciones

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.

Hay un patrón específico para combinar 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 las partes que deben ejecutarse siempre de la misma forma, como la verificación de identidad o la escalada, a un procedimiento estructurado.

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 conocimientos.
• No hay forma de finalizar el turno actual cuando se completa un procedimiento; el agente mantiene el turno abierto y puede seguir hablando.
• Las aristas del workflow no pueden conectarse a un procedimiento estructurado ni partir de él. Usa un paso Sub-procedure para encadenar procedimientos estructurados; la plataforma gestiona la entrada y la finalización.
• Iniciar un procedimiento añade latencia: el agente hace 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 selección forzada de herramientas. Es posible que otros modelos o proveedores personalizados no lo garanticen, lo que puede hacer menos fiables las transiciones a subprocedimientos o la finalización de procedimientos. Verifica que se admita la selección forzada de herramientas al usar otro proveedor de modelos.

Consulta Procedimientos para conocer los límites aplicables a todos los procedimientos, incluido el límite de tamaño del contenido y en qué se diferencian los procedimientos estructurados de los de formato libre.