ConfigurationComportement des agentsProcédures

Procédures structurées

Une séquence fixe d’étapes typées que votre agent exécute de la même manière à chaque fois

Présentation

Une procédure structurée est une procédure qui exécute une séquence fixe d’étapes. Une procédure en langage naturel fournit des indications en langage naturel que l’agent interprète et adapte à la situation. Une procédure structurée est une liste ordonnée d’étapes typées que l’agent exécute dans l’ordre chaque fois que la procédure s’applique.

Utilisez une procédure structurée lorsque certaines étapes doivent se dérouler de la même manière à chaque appel : vérifier l’identité d’un appelant, faire remonter un ticket ou effectuer un paiement. Vous la rédigez sous la forme d’une courte liste d’étapes en langage clair.

Comme toute procédure, une procédure structurée comporte un déclencheur qui décrit quand elle s’applique. Lorsqu’une conversation correspond au déclencheur, l’agent exécute les étapes de la procédure dans l’ordre, puis revient au reste de la conversation.

Éditeur de procédure structurée

Quand utiliser une procédure structurée

Utilisez une procédure structurée lorsque certaines étapes doivent toujours s’exécuter de la même façon, tout en vous permettant de les rédiger rapidement sous forme d’étapes simples. Les procédures structurées sont plus faciles à rédiger qu’un workflow, mais moins expressives. Pour découvrir comment elles se comparent aux procédures en langage naturel, aux workflows et au prompt système, consultez Quand utiliser des procédures.

Anatomie d’une procédure structurée

Une procédure structurée comporte trois éléments : un nom, un déclencheur et une liste ordonnée d’étapes.

Nom

Un libellé court qui identifie la procédure dans le Dashboard. Le nom n’est jamais envoyé au LLM ; il n’affecte donc pas le comportement de l’agent.

Déclencheur

Une description en langage naturel du moment où l’agent doit exécuter cette procédure, par exemple Lorsque l’utilisateur demande le remboursement d’une commande. L’agent compare l’intention de l’utilisateur au déclencheur de chaque procédure et exécute celle qui correspond ; les déclencheurs doivent donc être concrets et distincts. L’agent ne voit que le texte du déclencheur, jamais le nom ni l’ID de la procédure. Un déclencheur fonctionne comme pour toute autre procédure ; consultez Rédiger des déclencheurs.

Laissez le déclencheur vide pour faire de la procédure une sous-procédure qui ne s’exécute que lorsqu’une autre procédure l’appelle.

Étapes

Le corps de la procédure est une liste ordonnée d’étapes typées. Il existe plusieurs types d’étapes, que vous combinez pour décrire la tâche.

ÉtapeFonction
DemanderDemande des informations à l’utilisateur et attend sa réponse. Continue à demander jusqu’à ce que l’utilisateur réponde. C’est la seule étape qui attend l’utilisateur.
InformerDemande à l’agent de communiquer une information avec ses propres mots, puis passe à l’étape suivante.
DireDemande à l’agent d’énoncer un message exact mot pour mot, puis passe à l’étape suivante. Une étape Dire peut comporter une traduction configurée distinctement pour chaque langue prise en charge par l’agent.
OutilAppelle un outil spécifique. Vous pouvez indiquer au LLM en langage naturel comment appeler l’outil, ou définir explicitement les valeurs des paramètres lorsqu’un déterminisme maximal est nécessaire. Vous pouvez également définir les étapes à exécuter en cas d’échec de l’appel d’outil.
SiÉvalue une ou plusieurs conditions dans l’ordre et exécute les étapes de la première condition satisfaite. Un Sinon facultatif s’exécute lorsqu’aucune condition ne correspond.
Sous-procédureExécute une autre procédure structurée. Lorsque ses étapes sont terminées, le contrôle revient à l’étape suivante de cette procédure appelante.
Outil systèmeExécute une action système intégrée. Actuellement, seule la fin de l’appel est prise en charge.
RéessayerRéexécute le gestionnaire d’échec d’une étape Outil, appel d’outil inclus, jusqu’à trois fois. Disponible uniquement dans le gestionnaire d’échec d’une étape Outil.

Menu des types d'étapes de procédure structurée

Toutes les étapes ne peuvent pas apparaître partout. Dans une branche Si, vous pouvez utiliser n’importe quelle étape, sauf un autre Si ou Réessayer. Dans le gestionnaire d’échec d’une étape Outil, vous pouvez utiliser n’importe quelle étape, sauf Si ou un autre Outil.

Référence des étapes de l’API

Le content d’une procédure structurée est un document encodé en JSON qui contient un tableau steps. Chaque étape est un objet identifié par son type. Le déclencheur est un champ distinct de premier niveau dans la procédure, et ne fait pas partie de content. Les charges utiles de l’API et des SDK utilisent type: "deterministic" pour la procédure elle-même.

Ask

Une étape Ask demande à l’agent de solliciter des informations et d’attendre que l’utilisateur fournisse une réponse appropriée.

  • Type API : ask
  • instruction : chaîne non vide obligatoire.
{
  "type": "ask",
  "instruction": "Ask the user for their order ID."
}

Tell

Une étape Tell demande à l’agent de générer un message unique avec ses propres mots. Elle n’attend pas de réponse de l’utilisateur avant de continuer.

  • Type API : tell
  • instruction : chaîne non vide obligatoire.
{
  "type": "tell",
  "instruction": "Explain that the refund normally takes five to ten business days."
}

Say

Une étape Say prononce le texte fourni exactement tel qu’il est écrit, puis continue. Fournissez message_translations pour donner à l’agent un message exact pour chaque langue supplémentaire qu’il prend en charge, indexé par code de langue.

  • Type API : say
  • message : chaîne non vide obligatoire.
  • message_translations : objet facultatif qui associe un code de langue à { "value": "..." }.
{
  "type": "say",
  "message": "Your refund has been submitted.",
  "message_translations": {
    "es": { "value": "Su reembolso ha sido enviado." }
  }
}

If, else if et else

Une étape If contient un ou plusieurs embranchements conditionnels ordonnés. Le premier embranchement correspondant s’exécute. Le tableau fallback facultatif correspond à l’embranchement Else.

  • Type API : branch
  • branches : liste non vide d’embranchements conditionnels obligatoire.
  • fallback : liste facultative d’étapes Else.
  • Chaque embranchement requiert une condition et une liste steps non vide.
{
  "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."
    }
  ]
}

Le comportement est celui d’un if/else-if/else :

  1. Les conditions sont évaluées dans l’ordre.
  2. Le premier embranchement correspondant s’exécute.
  3. Si aucune condition ne correspond, fallback s’exécute.
  4. Une fois l’embranchement terminé, la procédure rejoint la séquence principale.

L’exemple ci-dessus utilise une condition textuelle, que le modèle évalue en langage naturel. Les conditions peuvent également être des expressions appliquées à des variables dynamiques :

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

Une condition d’expression teste des variables dynamiques, renseignées par les résultats d’outils ou définies au démarrage de la conversation. Elle ne peut pas lire la réponse la plus récente de l’utilisateur. Pour créer un embranchement selon ce que l’utilisateur a dit, utilisez une condition textuelle.

Tous les embranchements d’une même étape If doivent utiliser le même type de condition : llm ou expression.

Tool

Une étape Tool appelle un outil spécifique.

  • Type API : tool_call
  • tool_id : ID d’outil non vide obligatoire. L’outil doit être associé à l’agent.
  • tool_name : nom d’outil obligatoire, correspondant à l’outil.
  • instruction : instruction facultative décrivant comment appeler l’outil.
  • schema_overrides : valeurs fixes facultatives pour les paramètres de l’outil.
  • on_failure : gestionnaire d’échec facultatif.
{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "instruction": "Look up the order using the order ID provided by the user."
}

Valeurs fixes des paramètres

Utilisez schema_overrides lorsqu’un paramètre doit toujours prendre une valeur spécifique. Le modèle ne voit pas un paramètre remplacé et ne le choisit pas. Les clés sont des chemins de paramètres dans le schéma de l’outil ; chaque valeur désigne une source :

sourceChampsComportement
constantconstant_valueEnvoie toujours la valeur indiquée.
dynamic_variabledynamic_variableEnvoie la valeur actuelle de la variable dynamique nommée.
llmprompt (facultatif)Laisse le modèle choisir la valeur, avec une surcharge de prompt facultative.
omitOmet le paramètre de l’appel.
{
  "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" }
  }
}

Gestion des échecs

Sans on_failure, l’échec d’un appel d’outil met fin à la conversation. Ajoutez on_failure pour exécuter plutôt des étapes de récupération.

  • fallback : liste non vide obligatoire des étapes exécutées lorsque l’outil échoue.
  • branches : réservé à la gestion conditionnelle des échecs. Laissez ce champ vide.
{
  "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 gestionnaire d’échec peut contenir des étapes Ask, Tell, Say, Sub-procedure, System tool et Retry. Il ne peut pas contenir d’étapes Tool ou If. Une fois le gestionnaire exécuté, la procédure continue avec l’étape qui suit l’étape Tool.

Retry

Une étape Retry réexécute le gestionnaire d’échec qui la contient, y compris l’appel d’outil. Chaque tentative appelle à nouveau l’outil et, s’il échoue de nouveau, réexécute chaque étape du gestionnaire. Lorsque toutes les tentatives sont épuisées, la conversation prend fin.

  • Type API : retry
  • max_retries : entier facultatif de 1 à 3. La valeur par défaut est 1.
  • La valeur compte les tentatives après l’appel d’outil initial.
  • Retry n’est valide qu’à l’intérieur de on_failure.
  • Retry doit être la dernière étape de son gestionnaire d’échec, car les étapes suivantes seraient inaccessibles.
{
  "type": "retry",
  "max_retries": 2
}

Sub-procedure

Une étape Sub-procedure exécute une autre procédure structurée. Lorsque les étapes de cette procédure sont terminées, l’exécution revient à l’étape qui suit l’étape Sub-procedure.

  • Type API : sub_procedure
  • procedure_id : ID de procédure non vide obligatoire.
  • La cible doit exister sur le même agent.
  • La cible doit être une procédure structurée.
  • Une procédure ne peut pas s’appeler elle-même.
{
  "type": "sub_procedure",
  "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3"
}

System tool

Une étape System tool exécute une action système intégrée.

  • Type API : system_tool
  • system_tool_name : nom d’outil système obligatoire.
  • Actuellement, seul end_call est pris en charge. D’autres outils système pourront être ajoutés ultérieurement.
  • Puisque end_call est terminal, il doit être la dernière étape de la séquence, de l’embranchement ou du gestionnaire d’échec qui le contient.
{
  "type": "system_tool",
  "system_tool_name": "end_call"
}

Règles de validation

La publication de l’agent ou l’enregistrement de son brouillon rejette toute procédure structurée qui enfreint l’une de ces règles. L’erreur indique l’étape concernée par son chemin.

  • Deux étapes If ne peuvent pas être placées l’une à la suite de l’autre.
  • Les étapes If ne peuvent pas être imbriquées.
  • Une étape If avec des conditions d’expression ne peut pas suivre directement une étape Ask.
  • Toutes les conditions d’une même étape If doivent être du même type : llm ou expression.
  • Retry ne peut apparaître qu’à l’intérieur de on_failure et doit y être la dernière étape.
  • end_call doit être la dernière étape de la liste dans laquelle il apparaît.
  • Le fallback d’un gestionnaire d’échec doit contenir au moins une étape.
  • Une Sub-procedure doit pointer vers une procédure structurée existante sur le même agent, et non vers elle-même.
  • tool_id doit correspondre à un outil de l’agent, tool_name doit correspondre à cet outil et schema_overrides doit correspondre au schéma de l’outil.
  • La liste steps, chaque instruction et chaque message doivent être non vides.

Pour savoir comment restructurer une procédure qui enfreint l’une de ces règles, consultez les bonnes pratiques.

Exemple complet d’API

Cet exemple gère l’annulation d’une commande selon le statut de l’expédition. Il fixe un paramètre d’outil, traite l’échec d’un appel d’outil, appelle une autre procédure structurée, puis met fin à l’appel.

{
  "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"
    }
  ]
}

Exécution d’une procédure structurée

La transformation des étapes d’une procédure structurée dans le format exécuté par l’agent s’appelle la compilation. La plateforme compile chaque procédure structurée lors de la publication ; vous n’avez rien à compiler vous-même. Le résultat compilé est actuellement visible sous forme de nœuds en lecture seule dans l’onglet Workflow.

Lorsque la demande de l’utilisateur correspond au déclencheur d’une procédure, l’agent entre dans la procédure et exécute ses étapes dans l’ordre. Au sein de la procédure structurée, l’agent se concentre sur chaque étape isolément. Lorsqu’il arrive à la fin, il reprend le reste de la conversation.

Les règles suivantes décrivent le comportement des étapes à l’exécution.

Toutes les étapes autres que Ask s’exécutent immédiatement, puis le contrôle passe à l’étape suivante du même tour. Une étape Tell ou Say transmet son message et continue. Aucune étape, à l’exception de Ask, ne met la conversation en pause, et aucune étape ne termine le tour en cours. Si vous avez besoin d’une information de l’utilisateur, utilisez une étape Ask. Si la conversation doit se terminer, utilisez l’outil système end_call.

Lorsque la dernière étape se termine, la procédure prend fin et l’agent reprend le reste de la conversation, le tour étant toujours ouvert, il peut donc continuer à parler. Lorsqu’une sous-procédure se termine, le contrôle revient à l’étape suivante de la procédure qui l’a appelée.

Une étape Tool ne peut pas créer d’embranchement selon un code de statut ou le corps de la réponse. Si l’outil réussit, la procédure continue. S’il échoue et que l’étape n’a pas de gestionnaire d’échec, la conversation prend fin. Si elle en a un, les étapes du gestionnaire s’exécutent et la procédure passe à l’étape suivante. Un Retry dans le gestionnaire réexécute l’outil et, s’il échoue à nouveau, chaque étape du gestionnaire, jusqu’à ce que l’outil réussisse ou que les tentatives soient épuisées. Si elles sont épuisées, la conversation prend fin.

Les conditions sont évaluées dans l’ordre et la première correspondance s’exécute. L’embranchement Else s’exécute lorsqu’aucune condition ne correspond. En l’absence de Else et si aucune condition ne correspond, la procédure passe à l’étape suivant le If. Un cas non géré n’est pas une erreur.

Aucune décision prise au sein d’un embranchement If n’est mémorisée par les étapes suivantes. Si une information obtenue dans un embranchement est nécessaire ultérieurement, conservez-la explicitement avec un appel d’outil ou une variable dynamique.

Seules les étapes Tool peuvent appeler des outils. Il n’est pas nécessaire d’indiquer à une étape Ask, Tell ou Say de ne pas appeler d’outils, elle ne le peut pas.

Gérer une procédure structurée

Ouvrez votre agent dans le Dashboard, puis sélectionnez Procedures. Utilisez + pour créer une procédure structurée. Ajoutez un déclencheur, sélectionnez un type pour chaque étape et publiez les modifications de l’agent.

Le Dashboard valide les procédures structurées à mesure que vous les modifiez. Si une procédure enfreint une règle de validation, le bouton Publish affiche un état d’erreur, l’onglet Procedures affiche un badge d’erreur et l’aperçu ne peut pas démarrer tant que la procédure n’est pas corrigée. Sélectionnez l’indicateur d’erreur pour voir quelle procédure et quelle étape sont concernées.

Éditeur de procédure structurée avec le bouton Publish en état d’erreur et un badge 1 Error

Boîte de dialogue des détails de validation répertoriant la procédure en échec et l’étape nécessitant un message

Bonnes pratiques

Chaque type d’étape applique déjà son propre comportement, vous avez donc rarement besoin de le préciser. Décrivez l’objectif de chaque étape et laissez le type d’étape s’occuper du reste. Les recommandations ci-dessous couvrent les cas qu’il est important de bien configurer.

Choisir les types d’étapes

Une étape Ask attend une réponse. Si vous regroupez plusieurs questions dans une même instruction, l’agent a tendance à en ignorer certaines ou à les fusionner. Utilisez une étape Ask par information.

Une étape Tell transmet son message et passe à la suite sans attendre. Une étape Tell formulée comme une question n’obtient jamais de réponse. Si une étape nécessite une réponse de l’utilisateur, utilisez Ask.

Une étape Ask avance dès qu’elle obtient une réponse appropriée. Si ce qui constitue une réponse n’est pas évident dans la question, précisez-le dans l’instruction, par exemple _Demandez l’identifiant de commande ; un identifiant valide comporte huit chiffres _.

Utilisez une étape Tell lorsque l’agent doit composer lui-même le message, et une étape Say lorsque la formulation doit être reproduite ou traduite à l’identique. Les deux transmettent exactement un message, il n’est donc pas nécessaire d’indiquer à une étape d’envoyer un seul message.

Les étapes Ask, Tell et Say ne peuvent pas appeler d’outils. Ajouter n’appelez aucun outil à ces étapes ajoute du bruit à l’instruction sans modifier le comportement.

Structurer la procédure

Deux étapes If ne peuvent pas être placées l’une à la suite de l’autre. Insérer une étape Tell ou Say sans rapport entre elles pour respecter cette règle amène l’agent à dire quelque chose qu’il ne devrait pas. Intégrez plutôt la seconde décision dans la première étape If sous forme de branches Else if supplémentaires, ou placez-la dans une sous-procédure.

Les étapes If ne peuvent pas être imbriquées. Lorsqu’une décision dépend d’une autre, placez la décision interne dans sa propre procédure structurée et appelez-la avec une étape Sub-procedure depuis la branche qui en a besoin.

Une étape If sans Else passe à l’étape suivante lorsqu’aucune condition ne correspond. Si le cas sans correspondance doit se comporter différemment, ajoutez une branche Else.

Les décisions prises dans une branche If ne sont pas mémorisées ensuite. Si une étape ultérieure dépend d’une information apprise dans une branche, enregistrez-la avec un appel d’outil ou une variable dynamique dans cette branche.

Les conditions d’expression testent des variables dynamiques. Placez une étape If qui les utilise juste après l’étape Tool qui définit ces variables. Pour créer une branche selon ce que l’utilisateur a dit, utilisez une condition de texte.

Lorsque plusieurs procédures structurées partagent la même séquence, par exemple le transfert à un humain, placez-la dans une procédure structurée avec un déclencheur vide et appelez-la depuis chacune. Les séquences copiées divergent au fil du temps.

Utiliser des outils

Une étape Tool appelle toujours son outil. Une condition écrite dans l’instruction, comme _ignorez cette étape si le ticket est déjà étiqueté _, ne peut pas empêcher l’appel. Si l’appel ne doit pas toujours avoir lieu, placez la condition dans une étape If avant l’étape Tool.

Lorsqu’un paramètre doit toujours prendre une valeur précise, définissez-le avec un remplacement constant dans schema_overrides. Une instruction comme définissez toujours le statut sur en attente demande au modèle de s’y conformer ; un remplacement est appliqué et ne peut pas être ignoré.

Sans on_failure, tout échec d’outil met fin à la conversation. Ajoutez un gestionnaire qui indique à l’utilisateur ce qui s’est passé, puis réessaie, transfère ou poursuit.

Une étape Tool exécute uniquement l’outil ; l’agent ne peut ni parler ni prendre de décision pendant son exécution. Pour parler à l’utilisateur ou créer une branche selon ce que l’outil a renvoyé, utilisez une étape distincte avant ou après l’étape Tool.

Rédiger les instructions

La procédure contrôle l’exécution de la suite, et l’agent n’a pas connaissance des étapes ultérieures pendant l’exécution de l’étape en cours. Laissez l’ordre des étapes gérer l’enchaînement.

Les phrases écrites dans les instructions d’étape, comme ceci est le dernier message de ce tour, demandent à l’agent d’appliquer une limite que la plateforme ne gère pas. Utilisez une étape Ask pour attendre l’utilisateur ou l’outil système end_call pour terminer la conversation.

Le ton, la mise en forme, les formules de clôture et les politiques de refus relèvent du prompt système. Une instruction d’étape doit indiquer uniquement ce qui est propre à cette étape.

Composer des procédures

Les recommandations générales pour composer des procédures s’appliquent aussi aux procédures structurées ; consultez Composer des procédures sur la page des procédures de forme libre.

Un modèle est propre au mélange des types : une procédure de forme libre peut référencer une procédure structurée. Conservez le traitement ouvert dans une procédure de forme libre et déléguez les parties qui doivent s’exécuter de la même manière à chaque fois, comme la vérification d’identité ou le transfert, à une procédure structurée.

Limites

  • Les étapes If ne peuvent pas être imbriquées, et deux étapes If ne peuvent pas être placées l’une à la suite de l’autre.
  • Le seul outil système pris en charge est end_call.
  • Les procédures structurées ne peuvent pas référencer de documents de la base de connaissances.
  • Il n’est pas possible de terminer le tour en cours lorsqu’une procédure se termine ; l’agent garde le tour ouvert et peut continuer à parler.
  • Une procédure structurée ne peut pas être démarrée depuis un nœud de workflow spécifique dans le Dashboard.
  • Démarrer une procédure ajoute de la latence : l’agent effectue un appel d’outil pour y entrer, puis parcourt le workflow généré.

Prise en charge par les fournisseurs de modèles

Les procédures structurées imposent des appels d’outil internes lors de l’entrée dans une sous-procédure et de l’exécution d’une procédure. Les principales familles de modèles OpenAI, Anthropic, Gemini et Grok prennent en charge le choix forcé d’outil. D’autres modèles ou fournisseurs personnalisés peuvent ne pas le garantir, ce qui peut rendre les transitions vers les sous-procédures ou la fin des procédures moins fiables. Vérifiez la prise en charge du choix forcé d’outil lorsque vous utilisez un autre fournisseur de modèles.

Consultez Procédures pour connaître les limites applicables à toutes les procédures, notamment la limite de taille du contenu et les différences entre procédures structurées et procédures de forme libre.