Procedimientos estructurados

Descripción general

Un procedimiento estructurado es un procedimiento que ejecuta una secuencia fija de pasos. Un procedimiento de formato libre consiste en 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 deban realizarse pasos específicos de la misma manera en cada llamada: verificar la identidad de quien llama, escalar un ticket o realizar un pago. Lo redactas como una lista breve de pasos en lenguaje sencillo.

Como cualquier procedimiento, 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.

Cuándo usar un procedimiento estructurado

Usa un procedimiento estructurado cuando unos pasos específicos deban ejecutarse siempre de la misma forma, pero quieras redactarlos rápidamente como pasos sencillos. Para ver cómo se compara 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 solicite el reembolso de un pedido. El agente compara la intención del usuario con el activador de cada procedimiento y ejecuta el que coincida, por lo que los activadores deben ser concretos y diferenciados. Un activador funciona igual que en cualquier procedimiento; consulta Redactar activadores.

Pasos

El cuerpo del procedimiento es una lista ordenada de pasos tipados. Hay varios tipos de pasos, que puedes combinar para describir la tarea.

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.

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."
}

Indicar

Un paso Indicar instruye al agente para generar un único mensaje con sus propias palabras. A diferencia de Preguntar, 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 tal como está escrito.

• Tipo de API: say
• message: Cadena obligatoria no vacía.

{
  "type": "say",
  "message": "Your refund has been submitted."
}

Si, else if y else

Un paso Si contiene una o más ramas condicionales ordenadas. Se ejecuta la primera rama que coincide. El array fallback opcional actúa como la rama else.

• Tipo de API: branch
• branches: Lista obligatoria no vacía de ramas condicionales.
• fallback: Lista opcional de pasos else.
• Cada rama requiere un 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."
    }
  ]
}

Su comportamiento es 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 en lenguaje natural. Las condiciones también pueden usar expresiones de workflow:

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

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

Un paso Si puede ser el primer paso del procedimiento. Sin embargo:

• Los pasos Si no pueden anidarse.
• No se pueden colocar dos pasos Si consecutivos.
• Una condición de expresión no puede seguir directamente a un paso Preguntar. Usa una condición de LLM para evaluar la respuesta de texto libre de un usuario.

Herramienta

Un paso Herramienta llama a una herramienta específica.

• Tipo de API: tool_call
• tool_id: ID de herramienta obligatorio no vacío.
• tool_name: Nombre de herramienta obligatorio.
• instruction: Instrucción opcional que describe cómo llamar a la herramienta.
• on_failure: Gestor 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."
}

Sin on_failure, una llamada de herramienta fallida detiene el procedimiento. Añade on_failure para gestionar errores específicos, volver a intentar la herramienta o continuar con pasos alternativos.

• branches: Lista opcional de condiciones ordenadas. Se ejecuta la primera rama que coincide.
• fallback: Lista obligatoria no vacía de pasos. Se ejecuta cuando no coincide ninguna rama.

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "on_failure": {
    "fallback": [
      {
        "type": "tell",
        "instruction": "Explain that the order could not be retrieved and offer to connect the user with support."
      }
    ]
  }
}

Las ramas del gestor de errores pueden contener pasos Preguntar, Indicar, Decir, Subprocedimiento, Herramienta del sistema y Reintentar. No pueden contener pasos Herramienta ni Si. Todas las ramas condicionales de un mismo gestor de errores deben usar el mismo tipo de condición.

Reintentar

Un paso Reintentar vuelve a intentar el paso Herramienta cuyo gestor de errores lo contiene.

• Tipo de API: retry
• max_retries: Entero opcional de 1 a 3. El valor predeterminado es 1.
• El valor cuenta los reintentos después de la llamada original a la herramienta.
• Reintentar solo es válido dentro de on_failure.
• Reintentar debe ser el paso final de su rama del gestor de errores porque los pasos posteriores serían inalcanzables.
• Si fallan todos los intentos, el procedimiento se detiene.

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

Subprocedimiento

Un paso Subprocedimiento ejecuta otro procedimiento estructurado. Cuando termina, 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 obligatorio de herramienta del sistema.
• 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 o rama que lo contiene.

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

Ejemplo completo de la API

Este ejemplo gestiona la cancelación de un pedido según el estado del envío. Vuelve a intentar una llamada de herramienta fallida, invoca otro procedimiento estructurado y después finaliza la llamada.

{
  "trigger": "When the user asks to cancel an order and request a refund.",
  "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.",
              "on_failure": {
                "fallback": [
                  {
                    "type": "retry",
                    "max_retries": 2
                  }
                ]
              }
            }
          ]
        }
      ],
      "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."
    },
    {
      "type": "system_tool",
      "system_tool_name": "end_call"
    }
  ]
}

Cómo se ejecuta un procedimiento estructurado

Cuando la solicitud del usuario coincide con el activador de un procedimiento durante una conversación, el agente entra en el procedimiento y ejecuta sus pasos en orden, siempre de la misma forma. Mientras está dentro del procedimiento, el agente se centra en esos pasos; cuando llega al final, vuelve al punto en el que se quedó en la conversación.

Si un paso Herramienta falla y no define on_failure, el procedimiento se detiene sin ejecutar los pasos restantes. Cuando se configura on_failure, el procedimiento ejecuta la primera rama de error que coincide o su alternativa obligatoria. Un error gestionado continúa con el siguiente paso del procedimiento, a menos que el gestor seleccionado vuelva a intentar la herramienta, finalice la llamada o invoque otra ruta terminal.

Gestionar un procedimiento estructurado

Prácticas recomendadas

Redactar pasos

Componer procedimientos

Las indicaciones generales para componer procedimientos también se aplican a los procedimientos estructurados; consulta Componer 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 escalación, en un procedimiento estructurado.

Limitaciones

• Los pasos If no se pueden anidar ni colocar uno tras otro.

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. Otros modelos o proveedores personalizados pueden no garantizarlo, lo que puede hacer que las transiciones a subprocedimientos o la finalización de procedimientos sean menos fiables. Comprueba la compatibilidad con la selección forzada de herramientas cuando uses 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 las diferencias entre los procedimientos estructurados y los de formato libre.