Strukturerade procedurer

En fast följd 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 följd av steg. En fri procedur ä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 är tillämplig.

Använd en strukturerad procedur när specifika steg måste ske på samma sätt i varje samtal: för att verifiera en uppringares identitet, eskalera ett ärende eller ta emot en betalning. Du skapar den som en kort lista med steg på vanlig svenska.

Precis som alla procedurer har en strukturerad procedur en utlösare som beskriver när den ska användas. 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 fortfarande vill skapa den snabbt med enkla steg. Strukturerade procedurer är enklare att skriva än ett workflow men mindre uttrycksfulla. Läs När du ska använda procedurer för en jämförelse med fria procedurer, workflows och systemprompten.

Delar 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 dashboarden. Namnet skickas aldrig till LLM:en, så det påverkar inte agentens beteende.

Utlösare

En beskrivning på naturligt språk av när agenten ska köra proceduren, till exempel När användaren ber om återbetalning för en beställning. Agenten jämför användarens avsikt med varje procedurs utlösare och kör den som matchar, så utlösarna bör vara konkreta och tydliga. Agenten ser bara 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 för att göra proceduren till en underprocedur som bara körs när en annan procedur anropar den.

Steg

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

Steg	Vad det gör
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 separat konfigurerad översättning för varje språk agenten stöder.
Verktyg	Anropar ett specifikt verktyg. Du kan instruera LLM:en på vanlig svenska om hur verktyget ska anropas, eller uttryckligen låsa parametervärden när maximal determinism krävs. Du kan också 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 matchningen. En valfri Annars körs när inget matchar.
Underprocedur	Kör en annan strukturerad procedur. När dess steg är klara återgår kontrollen till nästa steg i denna procedur (den anropande).
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 felhanteraren för ett Verktyg-steg, inklusive verktygsanropet, upp till tre gånger. Endast tillgängligt i felhanteraren för ett Verktyg-steg.

Meny för stegtyper i strukturerade
procedurer

Alla steg kan inte användas överallt. I en Om-gren kan du använda alla steg utom ytterligare ett Om eller Försök igen. I felhanteraren för ett Verktyg-steg kan du använda alla steg utom ett Om eller ytterligare ett Verktyg.

API-referens för steg

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.

Fråga

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

API-typ: ask
instruction: Obligatorisk, icke-tom sträng.

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

Berätta

Ett Berätta-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, icke-tom sträng.

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

Säg

Ett Säg-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 den stöder, nycklat efter språkkod.

API-typ: say
message: Obligatorisk, icke-tom sträng.
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." }
  }
}

Om, annars om och annars

Ett Om-steg innehåller en eller flera ordnade villkorsgrenar. Den första matchande grenen körs. Den valfria fallback-arrayen är Annars-grenen.

API-typ: branch
branches: Obligatorisk, icke-tom lista med villkorsgrenar.
fallback: Valfri lista med Annars-steg.
Varje gren kräver ett condition och en icke-tom steps-lista.

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

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

Exemplet ovan använder ett textvillkor som modellen utvärderar på naturligt språk. Villkor kan också vara uttryck över 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 Om-steg måste använda samma villkorstyp: antingen llm eller expression.

Verktyg

Ett Verktyg-steg anropar ett specifikt verktyg.

API-typ: tool_call
tool_id: Obligatoriskt, icke-tomt verktygs-ID. 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 specifikt 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 åsidosättning av prompten.
`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 avslutas konversationen om ett verktygsanrop misslyckas. Lägg till on_failure för att i stället köra återställningssteg.

fallback: Obligatorisk, icke-tom lista med steg som körs när verktyget misslyckas.
branches: Reserverat för villkorlig felhantering. Lämna det 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 steg av typen Fråga, Berätta, Säg, Underprocedur, Systemverktyg och Försök igen. Den kan inte innehålla Verktyg- eller Om-steg. När hanteraren har körts fortsätter proceduren med steget efter Verktyg-steget.

Försök igen

Ett Försök igen-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, varje 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.
Försök igen är endast giltigt i on_failure.
Försök igen måste vara det sista steget i felhanteraren eftersom senare steg annars inte kan nås.

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

Underprocedur

Ett Underprocedur-steg kör en annan strukturerad procedur. När den procedurens steg är klara återgår körningen till steget efter Underprocedur-steget.

API-typ: sub_procedure
procedure_id: Obligatoriskt, icke-tomt procedur-ID.
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"
}

Systemverktyg

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

API-typ: system_tool
system_tool_name: Obligatoriskt namn på systemverktyget.
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 den sekvens, gren eller felhanterare 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å Om-steg kan inte placeras direkt efter varandra.
Om-steg kan inte nästlas.
Ett Om-steg med uttrycksvillkor kan inte direkt följa efter ett Fråga-steg.
Alla villkor i ett Om-steg måste vara av samma typ, antingen llm eller expression.
Försök igen 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 Underprocedur 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.
Listan steps, varje instruction och varje message får inte vara tomma.

Läs Bästa praxis om hur du kan omstrukturera en procedur som bryter mot någon av dessa regler.

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 agentutkastet sparas eller agenten publiceras; skribenter behöver aldrig kompilera något själva.

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

Workflow-kanter kan inte anslutas till eller från en strukturerad procedur. Använd ett Underprocedur-steg för att kedja strukturerade procedurer. Plattformen hanterar start från en matchande utlösare och slutförande, inklusive att återge kontrollen till workflow-noden där proceduren startade.

Följande regler beskriver hur steg beter sig vid körning.

Endast Fråga väntar på användaren

Alla steg utom Fråga körs omedelbart och kontrollen går vidare till nästa steg inom samma tur. Ett Berätta- eller Säg-steg levererar sitt meddelande och fortsätter. Det finns inget steg som pausar konversationen förutom Fråga och inget steg som avslutar den aktuella turen. Om du behöver användarens inmatning använder du ett Fråga-steg. Om konversationen ska avslutas använder du systemverktyget end_call.

Att nå slutet på 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.

Verktygssteg skiljer bara mellan lyckat och misslyckat

Ett Verktyg-steg kan inte förgrena utifrån 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 Försök igen i hanteraren kör om verktyget och, om det misslyckas igen, varje steg i hanteraren, tills verktyget lyckas eller försöken är slut. Om de är slut avslutas konversationen.

Om-steg fortsätter när inget matchar

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

Om-grenar för inte tillstånd vidare

Ingenting som avgörs i en Om-gren koms ihåg av senare steg. Om något som lärs i en gren behövs senare måste du uttryckligen spara det med ett verktygsanrop eller en dynamisk variabel.

Fråga-, Berätta- och Säg-steg har inga verktyg

Endast Verktyg-steg kan anropa verktyg. Du behöver inte säga till ett Fråga-, Berätta- eller Säg-steg att inte anropa verktyg; det kan det inte.

Hantera en strukturerad procedur

Skapa via dashboarden

Hantera via CLI

Hantera via API

Öppna din agent i dashboarden och välj sedan Procedurer. 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 agentändringarna.

Dashboarden validerar strukturerade procedurer medan du redigerar. Om en procedur bryter mot en valideringsregel visar knappen Publicera ett felläge, fliken Procedurer 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.

Redigerare för strukturerade procedurer med knappen Publicera i felläge och en markering
med 1 fel

Dialogrutan Valideringsdetaljer 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 beskriva det uttryckligen. Skriv avsikten med varje steg och låt stegtypen sköta resten. Vägledningen nedan täcker de fall där det är viktigt att göra rätt.

För att testa en strukturerad procedur följer du Iterera på en procedur.

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 några eller slå ihop dem. Använd ett Ask-steg per informationsdel.

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 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 _Be om 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 formuleringen 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.

Säg inte åt steg utan verktyg att undvika verktyg

Ask-, Tell- och Say-steg kan inte anropa verktyg. Att skriva anropa inga verktyg i dem tillför brus till 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 bör säga. Lägg i stället in det andra beslutet i det första If-steget som ytterligare Else if-grenar, eller flytta det till en delprocedur.

Placera nästlade beslut i en delprocedur

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

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

Ett If-steg utan Else går vidare till nästa steg när inget matchar. Om fallet utan matchning ska bete sig 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 koms inte ihåg efteråt. Om ett senare steg beror på något som har lärts in 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 Tool- steget som anger dessa variabler. Använd ett textvillkor för att förgrena utifrån vad användaren sa.

Bryt ut delade steg till en delprocedur

När flera strukturerade procedurer delar samma sekvens, till exempel att eskalera till en människa, placerar 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 ett If-steg, inte med dess instruktion

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

Fastställ parametervärden i stället för att beskriva dem

När en parameter alltid måste ha ett specifikt värde anger du det med en constant-åsidosättning i schema_overrides. En instruktion som ange alltid status som väntande ber modellen att följa den; en åsidosättning tillämpas 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.

Begränsa Tool-steg till verktygsanropet

Ett Tool-steg kör bara verktyget; agenten kan inte prata eller fatta ett beslut under det. För att prata med användaren eller förgrena utifrån vad verktyget returnerade placerar du 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 styra sekvenseringen.

Försök inte avsluta turen med prosa

Meningar i steginstruktioner, till exempel det här ä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 regler för avslag hör hemma i system- prompten. En steginstruktion ska bara ange det som är specifikt för steget.

Kombinera procedurer

Den allmänna vägledningen för att kombinera procedurer gäller även strukturerade procedurer. Se Kombinera procedurer på sidan om fria procedurer.

Ett mönster är specifikt för att blanda typer: en fri procedur kan referera till en strukturerad. Behåll öppen hantering i en fri procedur och delegera de delar 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 nästlas, och två If-steg kan inte placeras direkt efter varandra.
Det enda systemverktyg 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.
Workflow-kanter kan inte ansluta till eller från en strukturerad procedur. Använd ett Sub-procedure-steg för att kedja strukturerade procedurer; start och slutförande hanteras av plattformen.
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 interna verktygsanrop när en delprocedur öppnas och en procedur slutförs. De största 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 mellan 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 fria procedurer.