A Claude API a gyakorlatban

Miért az API ismerete a felkészülés gerince

A Claude Certified Architect felkészülés minden útja egy közös ponthoz vezet, és ez a Claude API. Bármilyen agentic rendszert, MCP integrációt vagy Claude Code munkafolyamatot építünk, a háttérben ugyanaz az alapmechanizmus dolgozik. A modell kap egy kérést, feldolgozza, és választ ad. Ha ezt a réteget értjük, akkor a fölötte lévő minden absztrakció átláthatóvá válik. Az architekt nem attól lesz jó, hogy egyetlen eszközt kívülről fúj, hanem attól, hogy tudja, mi történik a felszín alatt, és tudatosan dönt a paraméterekről. Ez a lecke ezt az alapot rakja le.

Vezérfonalnak vegyünk egy fiktív magyar céget, a Zöldmező Biztosítót. A cég ügyfélszolgálati asszisztenst épít, amely a beérkező kérdésekre válaszol a biztosítási feltételek alapján. Minden témát ezen a példán keresztül nézünk meg, hogy lássuk, a döntések hogyan csapódnak le a valóságban.

A Messages API alapja

A Claude API szíve a Messages API. A hívás magja egy üzenetlista, amelyben minden elemnek van egy szerepe és egy tartalma. Két szerep létezik. A felhasználói szerep az, amit a rendszer vagy a végfelhasználó mond, az asszisztensi szerep pedig az, amit a modell válaszol. Egy beszélgetés tehát felhasználói és asszisztensi üzenetek váltakozó sorozata, amelyet a hívásban átadunk a modellnek.

Van egy harmadik elem, amely nem az üzenetlistában, hanem egy külön mezőben szerepel, és ez a rendszerprompt. A rendszerprompt adja meg a modell viselkedésének keretét. Itt írjuk le, hogy a Zöldmező Biztosító asszisztense udvarias, csak a hivatalos feltételekre támaszkodik, és nem talál ki olyan fedezetet, ami nem szerepel a dokumentumokban. A különbségtétel fontos. A rendszerprompt a tartós szerep és a szabályok helye, az üzenetlista pedig maga a párbeszéd. Aki ezt a kettőt tudatosan szétválasztja, tisztább és megbízhatóbb rendszert épít, mert a viselkedési szabályok nem keverednek össze az aktuális kérdéssel.

A modellcsalád és a választás logikája

A Claude nem egyetlen modell, hanem egy modellcsalád, amelynek tagjai a képesség és a sebesség mentén különböznek. Az architekt feladata nem az, hogy fejből tudja az aktuális verziók nevét, hanem az, hogy értse a választás elvét. A nagyobb, erősebb modell a nehéz feladatra való, ahol mély érvelés, összetett szabályok követése vagy pontos, kényes döntés a tét. A gyorsabb, olcsóbb modell a tömegre való, ahol sok egyszerű kérést kell rövid idő alatt, alacsony költséggel kiszolgálni.

A Zöldmező Biztosító példáján ez kézzelfogható. Ha egy ügyfél összetett kárrendezési esetről kérdez, ahol több feltétel együttes értelmezése kell, ott az erősebb modell a helyes választás. Ha viszont egyszerű, gyakori kérdés érkezik, hogy meddig tart az ügyfélszolgálat nyitva, arra a gyorsabb modell is bőven elég, és sokkal olcsóbban válaszol. A jó architektúra gyakran nem egyetlen modellt használ, hanem a feladat nehézségéhez igazítja a választást. A konkrét verziószámokat és árakat szándékosan nem rögzítjük, mert ezek időről időre változnak, az elv viszont marad.

A fő paraméterek szerepe

Néhány paraméter dönti el, milyen lesz a válasz minősége és jellege. Az első a válasz maximális hossza. Ez felső korlátot ad arra, hány tokent állíthat elő a modell egyetlen válaszban. Ha túl alacsonyra állítjuk, a válasz félbeszakadhat, ha viszont indokolatlanul magasra, feleslegesen nyitunk teret hosszú, elkalandozó szövegnek. A Zöldmező asszisztensénél a rövid, tényszerű válaszhoz szűkebb korlát is elég.

A második a hőmérséklet, amely a változatosságot szabályozza. Alacsony hőmérsékleten a modell kiszámíthatóbb, következetesebb, szinte mindig hasonlóan válaszol ugyanarra a kérdésre. Magasabb hőmérsékleten több a változatosság és a kreativitás, de kevesebb a kiszámíthatóság. Egy biztosítási asszisztensnél az alacsony hőmérséklet a helyes irány, mert itt a pontosság és a következetesség fontosabb, mint a szófordulatok színessége. Egy ötletgeneráló feladatnál épp fordítva.

A harmadik a rendszerprompt, amelyről már volt szó. Ez nem egyszerű paraméter, hanem a viselkedés kerete, és gyakran ez határozza meg leginkább a végeredmény minőségét. A három együtt adja a tudatos vezérlést. A modell képessége adott, de hogy ebből mit hozunk ki, azt jórészt ezek a beállítások döntik el.

A többfordulós beszélgetés kezelése

Sok fejlesztő itt lepődik meg először. A modell önmagában nem emlékszik semmire. Nincs beépített memóriája a korábbi fordulókról. Minden egyes hívás önálló, és a modell csak azt látja, amit abban a hívásban átadunk neki. Ha azt akarjuk, hogy a beszélgetés folytonos legyen, akkor a teljes eddigi előzményt vissza kell küldeni minden új kérésnél.

A Zöldmező asszisztensénél ez azt jelenti, hogy amikor az ügyfél a harmadik kérdését teszi fel, a hívás nemcsak ezt a kérdést tartalmazza, hanem az első kérdést, az arra adott választ, a második kérdést, az arra adott választ, és így tovább. A folytonosság illúzióját az alkalmazás tartja fenn azzal, hogy karbantartja és minden fordulóban újraküldi az üzenetlistát. Ennek két gyakorlati következménye van. Egyrészt az alkalmazásnak kell tárolnia a beszélgetést, másrészt a hívás egyre hosszabb lesz, ahogy a beszélgetés nő, és ez a költségre is kihat, hiszen egyre több tokent adunk át bemenetként.

A streaming

Alapesetben a modell akkor küldi vissza a választ, amikor az teljesen elkészült. Hosszabb válasznál ez érezhető várakozást jelenthet a felhasználónak. A streaming ezt oldja meg. Streaming módban a válasz nem egyben, hanem darabokban érkezik, ahogy a modell előállítja. A felhasználó látja, hogy a szöveg fokozatosan épül fel, hasonlóan ahhoz, ahogy a Claude felületén megjelenik a válasz.

Az érdemi különbség az érzékelt gyorsaság. A teljes válasz nem feltétlenül készül el hamarabb, de a felhasználó sokkal előbb kap visszajelzést, és nem néz egy üres képernyőt. A Zöldmező ügyfélszolgálati felületén a streaming jobb élményt ad, mert a válasz azonnal életre kel, ahelyett, hogy másodpercekig semmi sem történne. Architekt szemmel a streaming élménydöntés, amely a hosszabb válaszoknál sokat számít.

A költség alaplogikája

A Claude API költsége a tokenek alapján áll össze, és ehhez két oldalt kell szétválasztani. Van a bemenet, vagyis minden, amit a modellnek átadunk, a rendszerprompt, az üzenetlista, a teljes előzmény. És van a kimenet, vagyis amit a modell válaszként előállít. A kettő külön súllyal esik latba, és együtt adják a hívás költségét. Konkrét árat itt sem írunk, mert az változik, de a szerkezet állandó, és ezt kell értenie az architektnek.

Ebből több gyakorlati elv következik. A hosszú előzmény drágít, mert minden fordulóban újraküldjük, tehát érdemes átgondolni, mennyi múltat viszünk magunkkal. A túl nagyra állított maximális hossz is költséget vihet a rendszerbe. És a modellválasztás közvetlenül a költségre hat, hiszen a nagy volumenű, egyszerű kérdéseket olcsóbb modellel kiszolgálni tudatos döntés. A Zöldmező Biztosítónál a havi számla nagyrészt ezeken a döntéseken múlik, nem a technológián magán.

Miért fontos ez az architektnek

Az API a rendszer alapköve. Minden fölötte lévő réteg, az agent, az MCP eszköz, a Claude Code munkafolyamat, végső soron ezekre a hívásokra épül. Ha az architekt érti a Messages API szerkezetét, a modellválasztás elvét és a paraméterek hatását, akkor nemcsak működő, hanem jól méretezett és költséghatékony rendszert tervez. A paraméterek tudatos használata dönti el a minőséget és a költséget egyszerre. Ugyanaz a modell felfelé és lefelé is nagyot mozdulhat aszerint, hogy jól állítjuk-e be a rendszerpromptot, a hőmérsékletet, a hosszkorlátot, és jól választjuk-e meg a modellt a feladathoz.

A Zöldmező Biztosító példája végigkísérte a leckét, mert jól mutatja, hogy ezek nem elvont beállítások. Az erős kontra gyors modell választása, a szűk hőmérséklet, a beszélgetés visszaküldése és a token alapú költség mind közvetlenül hat arra, hogy az asszisztens jó válaszokat ad-e és mennyibe kerül. Az alábbi lépéssor összefoglalja, mi épül fel egyetlen jól megtervezett API hívásban.