Hoppa till innehållet
POLARISAI ACADEMY
R07-101 · Navigatör

Verktygsanrop, MCP och arbetsflöden

Efteråt kan du lista anropen i ett fast arbetsflöde, avvisa argument som bryter mot ett skrivet schema, och räkna hur många gånger lagret ändras när samma idempotency key eller samma händelse-id kommer igen.

Nivå
Navigatör
Tid
24 h (uppskattning)
Förkunskap
F01–F07, R02-201
Kurs 1 av 4
Hoppa till

Efter kursen kan du

Eleven kan bygga en kompatibel MCP-server som exponerar typade, idempotenta verktyg och en agentklient som väljer och kör den korrekta verktygssekvensen över 30 frysta flerstegsscenarier.

Ett fast arbetsflöde och en agentloop

Ett deterministiskt arbetsflöde är en följd som är nedskriven innan den körs. Vanlig kod kan köra den, och det kan också en nodredigerare. Varje ruta namnger ett verktyg, och trådarna namnger den enda ordning som gäller. För en betald muggorder använder lektionen fyra steg: lookup_price, sedan reserve_stock, sedan charge_card, sedan mark_paid. lookup_price läser bara ett pris. reserve_stock och charge_card ändrar det som ligger lagrat. mark_paid körs när en webhook kommer, alltså ett HTTP-anrop som ett yttre system skickar till din mottagare. Med samma sku och samma antal stannar stegen i den ordningen. Värdprogrammet, programmet som håller chatten och kör verktygen, följer listan. Ett anrop till charge_card medan ordern saknar en lagrad reservering ger koden out_of_order, flyttar 0 cent och lämnar kortet orört.

En agentloop frågar språkmodellen i varje varv. Värdprogrammet skickar verktygslistan och resultaten hittills. Modellen svarar med ett verktygsnamn och ett argumentsobjekt, eller med en avslutande mening, och då tar loopen slut. Värdprogrammet kör det enda anropet, lägger till resultatet och frågar igen. Modellen kan upprepa en läsning, hoppa över ett steg eller namnge charge_card före reserve_stock. I lektionen tar loopen slut efter 8 verktygsanrop. Det åttonde anropet körs fortfarande när schemat godkänner det. Ett nionde anrop startar aldrig. Värdprogrammet stannar med koden step_cap. Taket är en regel i den här lektionen, så du kan räkna det på papper. Ett fast arbetsflöde och en agentloop kan dela samma fyra verktyg. Ordningen i arbetsflödet sitter i grafen. Ordningen i loopen är det modellen skickar ut, och värdprogrammet kontrollerar den före varje körning.

Schemat som kontrolleras före kroppen

Värdprogrammet kontrollerar argumenten mot ett schema innan verktygskroppen körs. Lektionen använder en liten del av JSON Schema. Värdet ska vara ett objekt. additionalProperties är false, så en nyckel som schemat utelämnar underkänns. required listar nycklarna som måste finnas. Varje egenskap har en typ. För reserve_stock är egenskaperna sku som sträng, qty som heltal med minimum 1, och idempotency_key som sträng, och alla tre krävs. qty 0 klarar inte minimigränsen. Ett negativt qty klarar den inte heller. Ett qty skrivet som sträng klarar inte typen, även när tecknen ser ut som ett tal. lookup_price kräver bara sku. charge_card kräver order_id som sträng, cents som heltal med minimum 1, och idempotency_key som sträng. Gå igenom reglerna en nyckel i taget. Ett godkänt objekt får gå in i kroppen. Ett underkänt anrop ändrar inget lager och drar inget på kortet.

I Model Context Protocol (MCP), det öppna protokoll en chattjänst använder för att nå verktyg, är det servern som visar schemat. Klienten frågar med metoden tools/list. Varje verktyg i svaret har ett namn, en beskrivning och ett inputSchema. Servern i lektionen listar fyra verktyg: lookup_price, reserve_stock, charge_card och mark_paid. Klienten anropar ett av dem med tools/call. Parametrarna bär det namnet och ett argumentsobjekt. Meddelandena är JSON-RPC 2.0. En schemamiss är ett protokollfel: svaret har ett felobjekt, och verktygskroppen körs noll gånger. Specifikationens exempel för ett okänt verktygsnamn är ett JSON-RPC-fel med koden -32602. Ett fel inuti ett verktyg som faktiskt körts har en annan form. Svaret är ett vanligt resultat, fältet isError är true, och ett innehållsblock bär texten som modellen kan läsa i nästa varv. Specifikationen säger att en server ska validera varje verktygsindata, och att en människa ska kunna neka ett anrop. Värdprogrammet i lektionen validerar argumenten, och det visar cent och nyckel före en dragning.

En nyckel, en sidoeffekt

En sidoeffekt ska landa en gång när samma begäran levereras två gånger. Anroparen skickar med en idempotency key, en sträng den valt för just den avsedda ändringen. Verktyget håller en liggare från nyckeln till det första lagrade resultatet. Det första godkända anropet med en ny nyckel gör ändringen och lagrar resultatet. Ett senare anrop med samma nyckel och samma argument lämnar tillbaka det lagrade resultatet och gör ändringen noll gånger till. Ett senare anrop med samma nyckel och andra argument gör ingenting och ger koden key_reused. En läsning som lookup_price har ingen liggarpost. Att köra den två gånger lämnar de lagrade talen som de var, så en upprepad läsning är ofarlig även utan nyckel. Reservering och dragning är anropen som behöver en nyckel, eftersom båda skriver.

En webhook använder samma liggartanke med ett händelse-id. Mottagaren lagrar event_id efter en lyckad hantering. Den första POST vars event_id är nytt får köra mark_paid en gång. En andra POST med samma event_id lämnar tillbaka den lagrade kvittensen och kör mark_paid noll gånger till. Ett annat event_id är en ny händelse och får köra mark_paid en gång till. Räkna HTTP-anrop och lagändringar som två olika summor. Två POST och en lagändring är en vanlig dubblettleverans. Tre POST kan fortfarande vara två lagändringar när två av dem delar id och det tredje id:t är nytt. Idempotency key och händelse-id är båda strängar du lagrar. Nyckeln skyddar ett anrop du skickar. Händelse-id skyddar ett anrop ett yttre system skickar till dig. En ny nyckel vid ett nytt försök av en dragning som kanske redan landat skulle öppna en andra dragning. Behåll nyckeln.

Strukturerade fel och nya försök

När verktygskroppen körs och affärssteget inte kan avslutas lämnar verktyget ett strukturerat fel som värdprogrammet kan grena på. Lektionen använder fyra fält: ok satt till false, en kodsträng, retryable satt till true eller false, och en kort detalj. Pappersregeln är liten. Om retryable är true och antalet försök hittills för den nyckeln är under 3, skicka samma argument och samma nyckel igen. Om det antalet redan är 3, stanna med koden retries_exhausted och skicka inget fjärde försök. Om retryable är false, stanna genast. invalid_arguments har retryable false, och i lektionen betyder den koden att kroppen kördes noll gånger. card_declined har retryable false. timeout har retryable true. step_cap har retryable false. out_of_order har retryable false. key_reused har retryable false.

Ett borttappat svar är fallet liggaren finns till för. Servern kan redan ha lagrat lyckan och dragit på kortet, medan klienten bara såg en timeout. Det nya försöket använder samma nyckel. Liggaren lämnar tillbaka den lagrade lyckan, så kortet dras en gång. Behandla en timeout som okänd tills liggaren svarar. En färsk nyckel efter en timeout skulle be om en andra dragning. I en agentloop ser modellen det strukturerade felet som verktygsinnehåll med isError true, och värdprogrammet håller ändå försöksregeln. Modellen väljer inget fjärde försök, och den byter ingen nyckel efter en timeout. Samma grenning fungerar i ett fast arbetsflöde: noden som tar emot timeout skickar antingen det identiska anropet igen eller stannar, med regeln ovan och ingen annan.

Ett exempel

Order 17, räknad för hand

Order 17 köper 2 enheter av sku MUG. lookup_price ger 450 cent för en enhet. Radsumman är 2 × 450 = 900 cent. Lagret av MUG börjar på 10. Reserveringen använder sku MUG, qty 2 och idempotency key ord-17-reserve. Argumenten matchar schemat: de tre krävda nycklarna finns, qty är ett heltal på minst 1, och ingen extra nyckel följer med. Första anropet reserverar 2 och lagrar resultatet. Lager kvar är 10 − 2 = 8. Nätet levererar sedan samma argument igen. Liggaren hittar ord-17-reserve, lämnar tillbaka stock_left 8, och lagret stannar på 8. Mottagna reserveringsanrop: 2. Antal gånger lagret minskade: 1. Personen har redan bekräftat en dragning på 900 cent, kontrollen värdprogrammet visar innan ett känsligt verktyg körs.

charge_card använder nyckeln ord-17-charge och 900 cent. Servern drar 900 cent och lagrar resultatet, sedan försvinner svaret. Klienten ser timeout. timeout har retryable true, och försöksräknaren står på 1, som är under 3, så klienten skickar samma nyckel och samma 900 igen. Liggaren lämnar tillbaka den lagrade lyckan. Kortet visar en dragning på 900 cent. En webhook kommer sedan med event_id evt-88, och mottagaren kör mark_paid en gång. En andra leverans av evt-88 lämnar tillbaka den lagrade kvittensen, och mark_paid stannar på en körning. Leveranser av evt-88: 2. Körningar av mark_paid: 1. För sig själv: en reservering vars qty är strängen 2 klarar inte heltalskontrollen. Värdprogrammet antecknar invalid_arguments, kroppen körs noll gånger, och det anropet lämnar lagret oförändrat. Ett charge_card utan lagrad reservering för ordern ger out_of_order, och kortet flyttas med 0 cent.

Övning

Order 21 på papper

Order 21 köper sku BOWL för 325 cent styck, antal 4. Räkna radsumman i cent. Lagret börjar på 6. Ta först argumenten sku BOWL och qty 4 utan idempotency_key. Namnge koden, säg om kroppen körs, och skriv lagret efter det försöket. Godkänn sedan en reservering med nyckeln ord-21-reserve och qty 4, och lägg till två vidare anrop med samma nyckel och samma qty. Skriv lagret och hur många gånger lagret minskade. Återanvänd sedan ord-21-reserve med qty 3, och skriv lagret och koden. Chargservern lagrar en lycka för radsumman och klienten ser en timeout, sedan försöker klienten igen med samma nyckel. Skriv hur många dragningar som träffar kortet, i cent. Webhooken levererar evt-21 två gånger och evt-22 en gång. Skriv hur många gånger mark_paid körs. För vart och ett av de fyra resultaten, namnge vad värdprogrammet gör: card_declined, en timeout på försök 1, invalid_arguments, och step_cap efter 8 verktygsanrop.

Radsumman är 325 × 4 = 1300 cent. Anropet utan nyckel är invalid_arguments, kroppen körs noll gånger, och lagret stannar på 6. Den godkända reserveringen lämnar 6 − 4 = 2. De två nya försöken lämnar tillbaka det lagrade resultatet, lagret stannar på 2, och lagret minskade en gång. Återanvändningen med qty 3 ger key_reused och lagret stannar på 2. Kortet tar en dragning på 1300 cent. evt-21 kör mark_paid en gång och dubbletten kör det noll gånger till, sedan kör evt-22 det en gång, så mark_paid körs 2 gånger över 3 leveranser. card_declined stannar genast. Timeout på försök 1 försöker igen med samma nyckel, eftersom 1 är under 3. invalid_arguments kör kroppen noll gånger. step_cap stannar loopen, och ett nionde anrop startar aldrig.

Kontrollfrågor

Svara själv först. Öppna sedan frågan för att se svaret.

I order 17 kostar en mugg 450 cent och antalet är 2. Vilken radsumma i cent blir det, och vad är stock_left efter det nya försöket med nyckeln ord-17-reserve?

900 cent. stock_left är 8. Lagret gick från 10 till 8 vid första reserveringen, och det nya försöket lämnade det på 8.

Ett tools/call för reserve_stock skickar qty som en sträng. Körs verktygskroppen, och vilken lektionskod antecknar värdprogrammet?

Kroppen körs noll gånger. Värdprogrammet antecknar invalid_arguments. Missen är ett protokollfel, så svaret har ett felobjekt i stället för ett verktygsresultat med isError.

För nyckeln ord-17-charge lagrade servern en dragning på 900 cent och klienten såg en timeout. Klienten skickar samma nyckel och samma 900 igen. Hur många dragningar ligger på kortet?

En dragning på 900 cent. Det andra anropet lämnar tillbaka det lagrade resultatet och gör dragningen noll gånger till.

Hur många gånger körs mark_paid när evt-88 levereras två gånger, och vad gör värdprogrammet när retryable är false?

mark_paid körs en gång. När retryable är false stannar värdprogrammet genast och skickar det anropet ingen ytterligare gång.

Ta med dig

Lagret ändras en gång när schemat godkänner argumenten och samma idempotency key eller samma händelse-id lämnar tillbaka det lagrade resultatet vid varje senare leverans. Ett fast arbetsflöde skriver anropsordningen, och en agentloop måste ändå lyda det schemat, den nyckeln och taket på 3 försök.

Slutuppgift

Lämna in en MCP-server och klient i Python eller TypeScript som klarar 30 fasta automatiserade tester av protokoll, schemavalidering, idempotens och felåterhämtning mot en deterministisk modellstub.

Slutuppgiften rättas av fasta facit och automatiska tester när proven öppnar.

Begrepp i kursen

Kursen har inga egna begrepp i ordlistan ännu. Begrepp från tidigare kurser används här också.

Fler lektioner kommer

Första lektionen är öppen att läsa. Resten av kursens lektioner skrivs, och prov och diplom kommer senare. Till väntelistan