Strukturerade procedurer

En fast sekvens av typade steg som din agent kör på samma sätt varje gång

Översikt

En strukturerad procedur är en procedur som kör en fast sekvens av steg. En friformsprocedur är vägledning på naturligt språk som agenten tolkar och anpassar efter situationen. En strukturerad procedur är en ordnad lista med typade steg som agenten kör i ordning varje gång proceduren gäller.

Använd en strukturerad procedur när specifika steg måste utföras på samma sätt vid varje samtal: verifiera en uppringares identitet, eskalera ett ärende eller ta emot en betalning. Du skriver den som en kort lista med steg på klarspråk.

Precis som alla procedurer har en strukturerad procedur en utlösare som beskriver när den gäller. När en konversation matchar utlösaren kör agenten procedurens steg i ordning och återgår sedan till resten av konversationen.

När du ska använda en strukturerad procedur

Använd en strukturerad procedur när specifika steg måste köras på samma sätt varje gång, men du ändå vill kunna skriva snabbt med enkla steg. Strukturerade procedurer är enklare att skriva än ett workflow, men mindre uttrycksfulla. Information om hur de jämförs med friformsprocedurer, workflows och systemprompten finns i När du ska använda procedurer.

Delarna i en strukturerad procedur

En strukturerad procedur har tre delar: ett namn, en utlösare och en ordnad lista med steg.

Namn

En kort etikett som identifierar proceduren i kontrollpanelen. Namnet skickas aldrig till LLM:en och påverkar därför inte agentens beteende.

Utlösare

En beskrivning på klarspråk av när agenten ska köra proceduren, till exempel När användaren ber om återbetalning för en order. Agenten jämför användarens avsikt med varje procedurs utlösare och kör den matchande proceduren, så utlösarna bör vara konkreta och tydligt åtskilda. Agenten ser endast utlösartexten, aldrig procedurens namn eller ID. En utlösare fungerar på samma sätt som för alla procedurer; se Skriva utlösare.

Lämna utlösaren tom om du vill göra proceduren till en delprocedur som endast körs när en annan procedur anropar den.

Steg

Procedurkroppen är en ordnad lista med typade steg. Det finns flera stegtyper som du kombinerar för att beskriva uppgiften.

Steg	Funktion
Fråga	Ber användaren om information och väntar. Den fortsätter fråga tills användaren svarar. Detta är det enda steget som pausar för användaren.
Berätta	Låter agenten förmedla något med egna ord och går sedan vidare till nästa steg.
Säg	Låter agenten säga ett exakt meddelande ord för ord och går sedan vidare till nästa steg. Ett Säg-steg kan ha en särskilt konfigurerad översättning för varje språk som agenten har stöd för.
Verktyg	Anropar ett specifikt verktyg. Du kan instruera LLM:en på klarspråk om hur verktyget ska anropas, eller uttryckligen låsa parametervärden när maximal determinism krävs. Du kan även definiera steg som körs om verktygsanropet misslyckas.
Om	Utvärderar ett eller flera villkor i ordning och kör stegen för den första träffen. Ett valfritt Annars körs när inget matchar.
Delprocedur	Kör en annan strukturerad procedur. När dess steg är klara återgår kontrollen till nästa steg i den här (anropande) proceduren.
Systemverktyg	Utför en inbyggd systemåtgärd. För närvarande stöds endast att avsluta samtalet.
Försök igen	Kör om ett Verktygs-stegs felhanterare, inklusive verktygsanropet, upp till tre gånger. Endast tillgängligt i ett Verktygs-stegs felhanterare.

Meny för stegtyper i strukturerade procedurer

Alla steg kan inte förekomma överallt. I en Om-gren kan du använda alla steg utom ytterligare ett Om eller Försök igen. I ett Verktygs-stegs felhanterare kan du använda alla steg utom ett Om eller ytterligare ett Verktyg.

API-stegreferens

En strukturerad procedurs content är ett JSON-kodat dokument som innehåller en steps-array. Varje steg är ett objekt som identifieras av sin type. Utlösaren är ett separat fält på toppnivå i proceduren, inte en del av content. API- och SDK-payloads använder type: "deterministic" för själva proceduren.

Ask

Ett Ask-steg instruerar agenten att be om information och vänta tills användaren ger ett lämpligt svar.

API-typ: ask
instruction: Obligatorisk sträng som inte får vara tom.

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

Tell

Ett Tell-steg instruerar agenten att generera ett enda meddelande med egna ord. Det väntar inte på ett användarsvar innan det fortsätter.

API-typ: tell
instruction: Obligatorisk sträng som inte får vara tom.

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

Say

Ett Say-steg säger den angivna texten exakt som den är skriven och fortsätter sedan. Ange message_translations för att ge agenten ett exakt meddelande för varje ytterligare språk som den stöder, med språkkod som nyckel.

API-typ: say
message: Obligatorisk sträng som inte får vara tom.
message_translations: Valfritt objekt som mappar en språkkod till { "value": "..." }.

{
  "type": "say",
  "message": "Your refund has been submitted.",
  "message_translations": {
    "es": { "value": "Su reembolso ha sido enviado." }
  }
}

If, else if och else

Ett If-steg innehåller en eller flera ordnade villkorsgrenar. Den första grenen som matchar körs. Den valfria fallback-arrayen är Else-grenen.

API-typ: branch
branches: Obligatorisk lista med villkorsgrenar som inte får vara tom.
fallback: Valfri lista med Else-steg.
Varje gren kräver ett condition och en steps-lista som inte får vara tom.

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

Detta fungerar som if/else-if/else:

Villkoren utvärderas i ordning.
Den första grenen som matchar körs.
Om inget villkor matchar körs fallback.
När en gren är klar återansluts proceduren till huvudsekvensen.

Exemplet ovan använder ett textvillkor som modellen utvärderar på naturligt språk. Villkor kan också vara uttryck som använder dynamiska variabler:

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

Ett uttrycksvillkor testar dynamiska variabler, som fylls i av verktygsresultat eller anges när konversationen startar. Det kan inte läsa användarens senaste svar. Använd ett textvillkor för att förgrena baserat på vad användaren sa.

Alla grenar i ett If-steg måste använda samma villkorstyp: antingen llm eller expression.

Tool

Ett Tool-steg anropar ett specifikt verktyg.

API-typ: tool_call
tool_id: Obligatoriskt verktygs-ID som inte får vara tomt. Verktyget måste vara kopplat till agenten.
tool_name: Obligatoriskt verktygsnamn som matchar verktyget.
instruction: Valfri instruktion som beskriver hur verktyget ska anropas.
schema_overrides: Valfria fasta värden för verktygets parametrar.
on_failure: Valfri felhanterare.

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "instruction": "Look up the order using the order ID provided by the user."
}

Fasta parametervärden

Använd schema_overrides när en parameter alltid måste ha ett visst värde. Modellen ser inte och väljer inte en åsidosatt parameter. Nycklar är parametersökvägar i verktygets schema; varje värde anger en källa:

`source`	Fält	Beteende
`constant`	`constant_value`	Skickar alltid det angivna värdet.
`dynamic_variable`	`dynamic_variable`	Skickar det aktuella värdet för den namngivna dynamiska variabeln.
`llm`	`prompt` (valfritt)	Låter modellen välja värdet med en valfri prompt-åsidosättning.
`omit`		Utesluter parametern från anropet.

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

Felhantering

Utan on_failure avslutar ett misslyckat verktygsanrop konversationen. Lägg till on_failure för att köra återställningssteg i stället.

fallback: Obligatorisk lista med steg som inte får vara tom och som körs när verktyget misslyckas.
branches: Reserverat för villkorsbaserad felhantering. Lämna tomt.

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

En felhanterare kan innehålla Ask-, Tell-, Say-, Sub-procedure-, System tool- och Retry-steg. Den kan inte innehålla Tool- eller If-steg. När hanteraren har körts fortsätter proceduren med steget efter Tool-steget.

Retry

Ett Retry-steg kör om felhanteraren som innehåller det, inklusive verktygsanropet. Varje försök anropar verktyget igen och kör, om det misslyckas igen, alla steg i hanteraren igen. När försöken är slut avslutas konversationen.

API-typ: retry
max_retries: Valfritt heltal från 1 till 3. Standardvärdet är 1.
Värdet räknar försök efter det ursprungliga verktygsanropet.
Retry är endast giltigt i on_failure.
Retry måste vara det sista steget i sin felhanterare eftersom senare steg inte skulle kunna nås.

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

Sub-procedure

Ett Sub-procedure-steg kör en annan strukturerad procedur. När procedurens steg är slutförda återgår körningen till steget efter Sub-procedure-steget.

API-typ: sub_procedure
procedure_id: Obligatoriskt procedur-ID som inte får vara tomt.
Målet måste finnas på samma agent.
Målet måste vara en strukturerad procedur.
En procedur kan inte anropa sig själv.

{
  "type": "sub_procedure",
  "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3"
}

System tool

Ett System tool-steg utför en inbyggd systemåtgärd.

API-typ: system_tool
system_tool_name: Obligatoriskt systemverktygsnamn.
För närvarande stöds endast end_call. Fler systemverktyg kan läggas till senare.
Eftersom end_call är avslutande måste det vara det sista steget i sekvensen, grenen eller felhanteraren som innehåller det.

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

Valideringsregler

När du publicerar agenten eller sparar agentutkastet avvisas en strukturerad procedur som bryter mot någon av dessa regler. Felet anger det felaktiga steget med dess sökväg.

Två If-steg kan inte placeras direkt efter varandra.
If-steg kan inte kapslas.
Ett If-steg med uttrycksvillkor kan inte direkt följa efter ett Ask-steg.
Alla villkor i ett If-steg måste vara av samma typ, antingen llm eller expression.
Retry får endast förekomma i on_failure och måste vara det sista steget där.
end_call måste vara det sista steget i den lista där det förekommer.
En felhanterares fallback måste innehålla minst ett steg.
En Sub-procedure måste peka på en befintlig strukturerad procedur på samma agent och inte på sig själv.
tool_id måste vara ett verktyg på agenten, tool_name måste matcha och schema_overrides måste matcha verktygets schema.
steps-listan, varje instruction och varje message får inte vara tomma.

Information om hur du kan omstrukturera en procedur som omfattas av någon av dessa regler finns i Bästa praxis.

Fullständigt API-exempel

Det här exemplet hanterar en orderannullering baserat på leveransstatus. Det låser en verktygsparameter, återhämtar sig från ett misslyckat verktygsanrop, anropar en annan strukturerad procedur och avslutar sedan samtalet.

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

Så körs en strukturerad procedur

Att omvandla en strukturerad procedurs steg till den form som agenten kör kallas kompilering. Plattformen kompilerar varje strukturerad procedur när du publicerar. Du behöver inte kompilera något själv. Det kompilerade resultatet visas för närvarande som skrivskyddade noder på fliken Workflow.

När användarens begäran matchar en procedurs utlösare går agenten in i proceduren och kör dess steg i ordning. I den strukturerade proceduren fokuserar agenten på varje steg var för sig. När den når slutet återgår den till resten av konversationen.

Följande regler beskriver hur steg fungerar vid körning.

Endast Ask väntar på användaren

Alla steg utom Ask körs direkt och kontrollen går till nästa steg inom samma tur. Ett Tell- eller Say-steg levererar sitt meddelande och fortsätter. Det finns inget steg som pausar konversationen utöver Ask och inget steg som avslutar den aktuella turen. Om du behöver användarens indata använder du ett Ask-steg. Om konversationen ska avslutas använder du systemverktyget end_call.

Att nå slutet av en procedur avslutar inte turen

När det sista steget är klart avslutas proceduren och agenten återgår till resten av konversationen medan turen fortfarande är öppen, så den kan säga mer. När en underprocedur är klar återgår kontrollen till nästa steg i proceduren som anropade den.

Tool-steg skiljer endast mellan framgång och fel

Ett Tool-steg kan inte förgrena baserat på en statuskod eller svarstexten. Om verktyget lyckas fortsätter proceduren. Om det misslyckas och steget saknar felhanterare avslutas konversationen. Om det har en körs hanterarens steg och proceduren fortsätter till nästa steg. Ett Retry i hanteraren kör om verktyget och, om det misslyckas igen, varje steg i hanteraren tills verktyget lyckas eller försöken tar slut. Om de tar slut avslutas konversationen.

If-steg fortsätter när inget matchar

Villkoren utvärderas i ordning och den första matchningen körs. Else-grenen körs när inget matchar. Om det inte finns någon Else och inget matchar fortsätter proceduren med steget efter If. Ett ohanterat fall är inte ett fel.

If-grenar för inte vidare tillstånd

Inget som beslutas i en If-gren kommer ihåg av senare steg. Om något som har lärts i en gren behövs senare ska du spara det uttryckligen med ett verktygsanrop eller en dynamisk variabel.

Ask-, Tell- och Say-steg har inga verktyg

Endast Tool-steg kan anropa verktyg. Du behöver inte säga till ett Ask-, Tell- eller Say-steg att inte anropa verktyg; det kan det inte.

Hantera en strukturerad procedur

Bygg via instrumentpanelen

Hantera via CLI

Hantera via API

Öppna din agent i instrumentpanelen och välj sedan Procedures. Använd + för att skapa en strukturerad procedur. Lägg till en utlösare, välj en typ för varje steg och publicera ändringarna i agenten.

Instrumentpanelen validerar strukturerade procedurer medan du redigerar. Om en procedur bryter mot en valideringsregel visar knappen Publish ett felläge, fliken Procedures visar en felmarkering och förhandsvisningen kan inte starta förrän proceduren har åtgärdats. Välj felindikatorn för att se vilken procedur och vilket steg som påverkas.

Redigeraren för strukturerade procedurer med knappen Publish i felläge och en markering för 1 Error

Dialogruta med valideringsinformation som listar den felande proceduren och steget som behöver ett
meddelande

Bästa praxis

Varje stegtyp styr redan sitt eget beteende, så du behöver sällan skriva ut det. Beskriv avsikten med varje steg och låt stegtypen sköta resten. Riktlinjerna nedan täcker de fall där det är viktigt att göra rätt.

Välja stegtyper

Ställ en fråga per Ask-steg

Ett Ask-steg väntar på ett svar. Om du samlar flera frågor i en instruktion tenderar agenten att hoppa över vissa eller slå ihop dem. Använd ett Ask-steg för varje informationsbit.

Använd Tell för påståenden och Ask för frågor

Ett Tell-steg levererar sitt meddelande och går vidare utan att vänta. Ett Tell-steg som formuleras som en fråga får aldrig något svar. Om ett steg behöver ett svar från användaren är det ett Ask-steg.

Ge ett Ask-steg ett tydligt avslutsvillkor när frågan i sig inte räcker

Ett Ask-steg går vidare när det har fått ett lämpligt svar. Om det inte framgår tydligt av frågan vad som räknas som ett svar, ange det i instruktionen, till exempel _Fråga efter order-ID:t; ett giltigt ID består av åtta siffror _.

Välj Tell för formuleringar, Say för exakta ord

Använd ett Tell-steg när agenten själv ska formulera meddelandet, och ett Say-steg när ordalydelsen måste vara ordagrann eller översatt. Båda levererar exakt ett meddelande, så du behöver inte instruera ett steg att skicka ett enda meddelande.

Be inte steg utan verktyg att undvika verktyg

Ask-, Tell- och Say-steg kan inte anropa verktyg. Att skriva anropa inga verktyg i dem skapar bara brus i instruktionen utan att ändra beteendet.

Strukturera proceduren

Lägg inte utfyllnad mellan två If-steg

Två If-steg kan inte placeras direkt efter varandra. Att lägga in ett orelaterat Tell- eller Say-steg mellan dem för att uppfylla regeln får agenten att säga något den inte borde. Lägg i stället det andra beslutet i det första If-steget som ytterligare Else if-grenar, eller flytta det till en delprocedur.

Lägg kapslade beslut i en delprocedur

If-steg kan inte kapslas. När ett beslut beror på ett annat lägger du det inre beslutet i en egen strukturerad procedur och anropar den med ett Sub-procedure-steg från den gren som behöver det.

Lägg till Else när ”inget av ovanstående” spelar roll

Ett If-steg utan Else fortsätter till nästa steg när inget matchar. Om det omatchade fallet ska hanteras annorlunda lägger du till en Else-gren för det.

Spara allt som ett senare steg behöver

Beslut som fattas i en If-gren kommer inte ihåg efteråt. Om ett senare steg beror på något som lärts i en gren, registrera det med ett verktygsanrop eller en dynamisk variabel i grenen.

Placera uttrycksvillkor efter verktyget som fyller i dem

Uttrycksvillkor testar dynamiska variabler. Placera ett If-steg som använder dem direkt efter det Tool- steg som sätter dessa variabler. Använd ett textvillkor för att förgrena utifrån vad användaren sa.

Bryt ut gemensamma steg till en delprocedur

När flera strukturerade procedurer delar samma sekvens, till exempel att eskalera till en människa, lägger du den i en strukturerad procedur med en tom utlösare och anropar den från var och en. Kopierade sekvenser glider isär med tiden.

Arbeta med verktyg

Styr ett Tool-steg med If, inte med dess instruktion

Ett Tool-steg anropar alltid sitt verktyg. Ett villkor som skrivs i instruktionen, till exempel _hoppa över detta om ärendet redan är taggat _, kan inte förhindra anropet. Om anropet inte alltid ska ske, lägg villkoret i ett If-steg före Tool-steget.

Lås parametervärden i stället för att beskriva dem

När en parameter alltid måste ha ett visst värde ska du ange det med en constant-åsidosättning i schema_overrides. En instruktion som ställ alltid in status på väntande ber modellen att följa den; en åsidosättning verkställs och kan inte hoppas över.

Ge varje Tool-steg en felhanterare

Utan on_failure avslutar alla verktygsfel konversationen. Lägg till en hanterare som berättar för användaren vad som hände och försöker igen, eskalerar eller fortsätter.

Låt Tool-steg bara hantera verktygsanropet

Ett Tool-steg kör bara verktyget; agenten kan inte prata eller fatta ett beslut medan det körs. För att prata med användaren eller förgrena utifrån vad verktyget returnerade ska du lägga det i ett separat steg före eller efter Tool-steget.

Skriva instruktioner

Beskriv bara det aktuella steget

Proceduren styr vad som körs härnäst, och agenten känner inte till senare steg medan den kör det aktuella. Låt stegordningen sköta sekvenseringen.

Försök inte avsluta turen med löpande text

Meningar som skrivs i steginstruktioner, till exempel detta är det sista meddelandet i den här turen, ber agenten att upprätthålla en gräns som plattformen inte har. Använd ett Ask-steg för att vänta på användaren eller systemverktyget end_call för att avsluta konversationen.

Behåll globala regler i systemprompten

Ton, formatering, avslutningsfraser och policyer för avböjanden hör hemma i system- prompten. En steginstruktion ska bara ange vad som är specifikt för det steget.

Kombinera procedurer

De allmänna riktlinjerna för att kombinera procedurer gäller även strukturerade procedurer; se Kombinera procedurer på sidan om frihandsprocedurer.

Ett mönster är specifikt för att blanda typer: en frihandsprocedur kan referera till en strukturerad procedur. Behåll öppen hantering i en frihandsprocedur och delegera delarna som måste köras på samma sätt varje gång, till exempel identitetsverifiering eller eskalering, till en strukturerad procedur.

Begränsningar

If-steg kan inte kapslas, och två If-steg kan inte placeras direkt efter varandra.
Det enda systemverktyget som stöds är end_call.
Strukturerade procedurer kan inte referera till kunskapsbasdokument.
Det går inte att avsluta den aktuella turen när en procedur slutförs; agenten håller turen öppen och kan fortsätta prata.
En strukturerad procedur kan inte startas från en specifik workflow-nod i dashboarden.
Att starta en procedur ökar latensen: agenten gör ett verktygsanrop för att gå in i den och går sedan igenom det genererade workflowet.

Stöd från modellleverantörer

Strukturerade procedurer tvingar fram interna verktygsanrop när de går in i en delprocedur och slutför en procedur. De större modellfamiljerna från OpenAI, Anthropic, Gemini och Grok stöder tvingande verktygsval. Andra modeller eller anpassade leverantörer kanske inte kan garantera detta, vilket kan göra övergångar till delprocedurer eller slutförande av procedurer mindre tillförlitliga. Kontrollera stödet för tvingande verktygsval när du använder en annan modellleverantör.

Se Procedurer för begränsningar som gäller alla procedurer, inklusive gränsen för innehållsstorlek och hur strukturerade procedurer skiljer sig från frihandsprocedurer.