# Kun AI-agentin API-kutsu pätkii, syntyy tuplatilaus: näin idempotenssi ja Saga-malli AI-agentin integraatioissa estävät ERP-virheet

> Verkkoviive saa AI-agentin luomaan tuplatilauksia ERP:hen. Katso, miten idempotenssi ja Saga-malli AI-agentin integraatioissa estävät virheet tuotannossa.

- Julkaistu: 2026-10-19
- Kirjoittaja: Master Mind
- Alkuperäinen: https://aimaster.fi/artikkelit/kun-ai-agentin-api-kutsu-patkii-syntyy-tuplatilaus-idempotenssi-ja-saga-malli

Yksi kolmen sekunnin verkkoviive riittää muuttamaan avuliaan tekoälyagentin koneeksi, joka kirjaa saman myyntitilauksen kahteen kertaan ja lukitsee varastosaldot. Idempotenssi ja Saga-malli AI-agentin integraatioissa ovat välttämätön arkkitehtuurivaatimus heti, kun kasvuyrityksesi siirtää agentit pelkästä tiedonhausta tekemään kirjauksia ERP-, WMS- ja laskutusjärjestelmiin. Internet Engineering Task Forcen HTTP-työryhmän spesifikaation mukaan (IETF, 2025, draft-ietf-httpapi-idempotency-key-header-07) tilaa muuttavat POST- ja PATCH-rajapintakutsut eivät ole oletuksena idempotentteja: jos yhteys katkeaa ennen kuittausta ja kutsu lähetetään uudelleen, kohdejärjestelmä suorittaa transaktion toistamiseen.

Useimmat kasvuyritykset huomaavat tämän puutteen vasta ensimmäisen tuotantohäiriön yhteydessä. Kun [structured outputs ja JSON-skeema tekoälyintegraatiossa](https://aimaster.fi/artikkelit/structured-outputs-ja-json-skeema-tekoalyintegraatiossa-estavat-rikkinaiset-erp-kutsut) varmistavat, että agentin lähettämä viesti on rakenteeltaan oikea, skeemavalidointi ei vielä kerro, onko täsmälleen sama tilaus kirjattu tietokantaan jo viisi sekuntia aiemmin.

## Miksi uudelleen yrittävä AI-agentti aiheuttaa tuplatilauksia ERP-järjestelmässä?

AI-agentti aiheuttaa tuplatilauksia, koska kielimalli ei pysty erottamaan epäonnistunutta tietokantakirjausta ja matkalla katkennutta verkkokuittausta toisistaan. Kun ERP-rajapinta vastaa hitaasti ja kutsu päättyy aikakatkaisuun (timeout), agentin ohjaussilmukka tulkitsee tehtävän epäonnistuneeksi ja lähettää uuden POST-kutsun, jolloin järjestelmään syntyy toinen identtinen tilaus tai lasku.

Kuten Brandur Leach kuvaa Stripen hajautettujen järjestelmien insinöörianalyysissä (Stripe Engineering, 2017, Designing robust and predictable APIs with idempotency), jokainen kahden järjestelmän välinen verkkokutsu voi epäonnistua kolmella eri tavalla: yhteys ei koskaan saavuta palvelinta, suoritus katkeaa palvelimella kesken ajon tai palvelin saa työn valmiiksi, mutta yhteys katkeaa ennen kuin vastaus palaa kutsujalle. Kolmannessa tilanteessa ERP on jo luonut myyntitilauksen, mutta AI-agentti näkee vain virheilmoituksen aikakatkaisusta.

Ilman transaktiotilan seurantaa agentti yrittää korjata tilanteen kutsumalla työkalua uudelleen. Jos rajapinta on ruuhkautunut ja useat agentti-istunnot yrittävät kutsua yhtä aikaa, hallitsemattomat uudelleenyritykset kaatavat lopulta koko taustajärjestelmän (thundering herd -ilmiö), ellei kutsuja porrasteta eksponentiaalisella odotusajalla ja satunnaisvaihtelulla eli jitterillä (Stripe Engineering, 2017). Kalvoarkkitehtuureissa verkkokatkoksia ei luonnollisesti esiinny, koska PowerPointissa jokainen nuoli menee perille ensimmäisellä yrittämällä.

## Miten idempotenssi ja Idempotency-Key estävät tuplasuoritukset AI-agentin integraatioissa?

Idempotenssi tarkoittaa, että saman rajapintakutsun suorittaminen yhden tai kymmenen kertaa tuottaa kohdejärjestelmässä täsmälleen saman lopputuloksen kuin yksi onnistunut kutsu. Tämä toteutetaan liittämällä jokaiseen tilaa muuttavaan työkalukutsuun yksilöllinen `Idempotency-Key`-otsikkotieto, jonka avulla vastaanottava järjestelmä tunnistaa uudelleenyrityksen ja palauttaa aiemman suorituksen tallennetun tuloksen ilman uutta tietokantakirjausta.

Tuotantoarkkitehtuurissa kriittinen sääntö on, ettei kielimalli saa itse keksiä idempotenssiavainta. Jos kielimalli generoi avaimen satunnaisesti työkalukutsun parametreihin, se luo virhetilanteessa uuden avaimen, jolloin suojaus pettää. Avain muodostetaan deterministisesti orkestrointikerroksessa yhdistämällä liiketoimintaobjektin tunniste, työnkulun ajotunniste ja työvaiheen nimi (esimerkiksi `tilaus_84920_ajo_12_luo_erp_tilaus`).

- Ensimmäinen kutsu: Integraatiokerros tallentaa idempotenssiavaimen nopeaan tilatauluun `IN_PROGRESS`-lukituksella ennen kuin se välittää POST-kutsun ERP-järjestelmään.
- Onnistunut kuittaus: Kun ERP palauttaa luodun tilausnumeron, integraatiokerros päivittää avaimen tilaksi `COMPLETED` ja tallentaa vastauksen välimuistiin.
- Uudelleenyritys aikakatkaisun jälkeen: Kun AI-agentti lähettää saman kutsun uudelleen samalla avaimella, integraatiokerros palauttaa tallennetun tilausnumeron suoraan välimuistista koskematta ERP-tietokantaan.
- Parametrien muuttumisen esto: IETF:n spesifikaation (IETF, 2025) mukaisesti rajapinta hylkää kutsun virheellä, jos samaa idempotenssiavainta yritetään käyttää muuttuneella tietosisällöllä.

## Miten Saga-malli peruuttaa puolitiehen jääneen ketjun, kun kolmas vaihe epäonnistuu?

Saga-malli hallitsee usean järjestelmän yli ulottuvia tapahtumaketjuja sitomalla jokaiseen eteenpäin vievään kirjaukseen käänteisen kompensaatiotoimenpiteen (compensating action), joka kumoaa tehdyn muutoksen virhetilanteessa. Kun AI-agentti varaa ensin tuotteet varastojärjestelmästä ja luo tilauksen ERP:hen, mutta kolmantena vaiheena ajettava luottorajatarkistus tai rahtivaraus epäonnistuu, Saga-orkestroija ajaa peruutustoimenpiteet käänteisessä järjestyksessä.

Nykyaikaisissa pilvi- ja ERP-ympäristöissä agentti ei voi lukita CRM:ää, varastonhallintaa ja talousjärjestelmää yhden yhteisen tietokantatransaktion (two-phase commit) sisään. Kuten Emily Fortuna osoittaa Temporalin hajautettujen työnkulkujen teknisessä oppaassa (Temporal, 2023, Saga compensating actions design pattern & Saga design pattern explained), Saga-malli korvaa järjestelmien väliset lukitukset paikallisilla kirjauksilla ja eksplisiittisellä kompensaatiopinolla, joka puretaan virheen sattuessa viimeisimmästä ensimmäiseen (LIFO, Last-In-First-Out).

Fortuna nostaa esiin myös kriittisen tuotantoyksityiskohdan: kompensaatiotoimenpide (`addCompensation`) on rekisteröitävä työnkulun lokiin *ennen* kuin varsinainen työkalukutsu ajetaan (Temporal, 2023). Jos varastosaldon varauskutsu päättyy aikakatkaisuun juuri sen jälkeen, kun varastojärjestelmä on lukinnut tuotteet, etukäteen rekisteröity kompensaatio (`vapautaVarastoJosVarattu`) varmistaa, ettei varaus jää roikkumaan. Lisäksi jokaisen kompensaatiokutsun on oltava itsessään idempotentti, jotta peruutusketju voidaan ajaa turvallisesti loppuun myös verkkohäiriön keskellä.

|  |
|  |

## Miten transaktioturvallinen AI-agentti rakennetaan Master OS -alustan päälle?

Transaktioturvallinen AI-agentti rakennetaan erottamalla liiketoimintapäättely ja tilanhallinta toisistaan: kielimalli päättää, mitä prosessissa pitää tehdä, ja integraatioalusta huolehtii idempotenssiavaimista, uudelleenyrityksistä ja Saga-kompensaatioista. AIMASTERilla tämä suojauskerros toteutetaan osana tuotantoarkkitehtuuria 3 päivän sprinteissä ilman kuukausien määrittelyprojekteja.

**[Master Plan](https://aimaster.fi/tuotteet/master-plan)** on tekoälystrategiasprintti, joka kartoittaa, missä tekoäly tuottaa yrityksellesi eniten arvoa — euroissa mitattuna. Samalla tunnistamme prosessit, joissa agentti siirtyy pelkästä tiedonhausta kirjoittamaan tilauksia, varauksia tai laskuja kohdejärjestelmiin, ja määrittelemme niille vaadittavat peruutussäännöt.

**[Master OS](https://aimaster.fi/tuotteet/master-layer)** on yrityksen AI Operating System: alusta, joka yhdistää yrityksen olemassa olevat järjestelmät (CRM, ERP, dokumentit), datan ja agentit turvallisesti tekoälyn käytettäväksi. Master OS:ssä agentin työkalukutsut eivät koskaan ammu suoraan suojaamattomiin ERP-rajapintoihin, vaan alusta liittää kutsuihin deterministiset idempotenssiavaimet ja valvoo Saga-ketjun etenemistä. **[Master Mind](https://aimaster.fi/tuotteet/master-mind)** on AI-agenttien kokonaisuus, joka toimii Master OS:n päällä ja hoitaa liiketoimintaprosesseja itsenäisesti. **Räätälöidyt AI-ratkaisut** toteutetaan ketterällä sprinttimallilla: yksi sprintti on 3 kehityspäivää.

Kun rakensimme Jaajo Linnonmaan Aini-tekoälyapulaisen ja automatisoimme digimarkkinointitoimisto Tagomon työnkulkuja, tuotantovarmuuden ydin oli aina sama: tekoälylle annetaan selkeät raamit, ja kriittiset järjestelmätoimenpiteet varmistetaan deterministisellä koodilla. Silloin yksikään hidas rajapinta ei pysäytä arkea tai sotke tilauskantaa.

Haluatko nähdä, mitkä yrityksesi tilaus-, varasto- tai laskutusprosessit kannattaa automatisoida AI-agenteilla ja miten ne suojataan tuplatilauksilta ennen tuotantoon vientiä? Varaa [Ilmainen Master Mind -analyysi](https://aimaster.fi/analyysi), niin kartoitamme yrityksesi arvokkaimmat agenttityönkulut ja niiden integraatioarkkitehtuurin euroissa mitattuna.

## Usein kysytyt kysymykset

### Riittävätkö structured outputs ja JSON-skeema estämään tuplatilaukset?

Eivät riitä. Structured outputs varmistaa vain sen, että agentin lähettämä viesti on muotonsa puolesta kelvollinen eikä kaada vastaanottavaa rajapintaa. Jos verkkoyhteys katkeaa vastauksen aikana ja agentti lähettää saman täydellisesti muotoillun viestin uudelleen, kohdejärjestelmään syntyy tuplatilaus ilman idempotenssiavainta.

### Kumpi luo idempotenssiavaimen: kielimalli vai integraatioalusta?

Idempotenssiavain luodaan deterministisesti orkestrointikerroksessa ennen työkalukutsua esimerkiksi yhdistämällä liiketoimintaobjektin tunniste, työnkulun ajotunniste ja työvaiheen nimi. Jos kielimalli arpoo uuden tunnisteen jokaisella uudelleenyrityksellä, kohdejärjestelmä tulkitsee kutsun uudeksi tilaukseksi.

### Voiko idempotenssin ja Saga-mallin lisätä vanhaan ERP-järjestelmään ilman ERP:n koodimuutoksia?

Vanhan ERP-järjestelmän lähdekoodia ei tarvitse muuttaa. Idempotenssitarkistus ja tilataulu rakennetaan ERP:n eteen tulevaan välityskerrokseen, joka suodattaa tuplakutsut ja tarjoaa Saga-orkestroijalle selkeät peruutusrajapinnat, kuten varauksen vapauttamisen tai hyvitystositteen luonnin.

### Miten Saga-malli eroaa perinteisestä tietokantatransaktiosta?

Kaksivaiheinen sitouttaminen (two-phase commit) lukitsee tietokantarivit kaikissa osallistuvissa järjestelmissä yhtä aikaa, mikä hidastaa järjestelmiä eikä toimi ulkoisten pilvirajapintojen yli. Saga-malli sitouttaa jokaisen vaiheen paikallisesti ja peruuttaa aiemmat vaiheet käänteisillä kompensaatiotoimenpiteillä, jos myöhempi vaihe epäonnistuu.