Designing APIs for Agents — Ben Swerdlow (2026-07-09)

Szerző: Ben Swerdlow (Freestyle founder/CEO) Dátum: 2026-07-09 • Forrás: https://www.freestyle.sh/blog/opinion/designing-apis-for-agents • Hossz: 13 min read (~3000 szó) Sorozat: Ez a 2. része a freestyle.sh "AI agent" esszé-sorozatának. Topic: ai-automation.md (API design for agents, AI-vezérelt rendszerek)

A szerző központi tézise

A 2026-os API-tervezés paradigmaváltáson megy keresztül. A legtöbb API-fogyasztó ma már agent-írt kódon keresztül dolgozik — ez két évvel ezelőtt még nem volt igaz. Swerdlow az elmúlt 24 hónapban három alapvető véleményt is megváltoztatott: korábban a hasznos utility-package-eket szerette, most anti-utility; korábban a rövid neveket preferálta, most extrém hosszúakat; korábban a defaults-ot (alapértelmezett értékeket) fontosnak tartotta, most kifejezetten rossznak tartja. Mindezt az új valósághoz való alkalmazkodásként.

"Good design for agents is not the same as good design for humans."

A cikk 7 fő szála

1. Miért más most a világ — az agent-ek beolvasnak mindent

Az átlagos Claude Code prompt 10 000+ token, és az agent-ek az első promptra be tudják olvasni a teljes API-dokumentációt és minden kapcsolódó dokumentumot. Másodpercek alatt több ezer sor kódot tudnak generálni. Ez a változás minden korábbi API-tervezési konvenciót megkérdőjelez.

"AI agents can read our entire docs in one sitting... This changes everything."

2. "Good APIs for humans" — a régi modell, ami már nem elég

Swerdlow azzal indít, hogy leírja a hagyományos ember-központú API-tervezést: sketch-elni a minimális use-case-eket, 50 sorban funkcionális kódot adni, ahol a kezdő user az autocomplete-ből ismeri meg a fennmaradó 19 mezőt. A Twilio és a Stripe SDK-k a példák: a 14 éves Swerdlow is tudott velük emailt küldeni és payment intentet létrehozni anélkül, hogy tudta volna, mi az ACH vagy a Twilio scheduling. Ezek az SDK-k lehetővé tették, hogy "haladj anélkül, hogy értenéd, mi történik valójában" — és pont ez az, ami agent-eknél pontosan fordítva működik.

3. "Good APIs for agents" — a négy alapelv

a) Defaults are bad. A default értékek (amiket a fejlesztő kitölt, hogy a usernek ne kelljen) most rosszak: az agent-ek el tudják olvasni a dokumentációt, regisztrálni a helyes kezdőértékeket, és explicit módon kitölteni minden mezőt. Az explicitség olcsó lett, és a specificitás csökkenti a bugokat. A Twilio példában 30 mezőt nem töltött ki Swerdlow — egy agent-nek mind a 30-at ki kellene töltenie. A fontos és kevésbé fontos mezőket persze komment-sorral el kell választani, de a kitöltés "adója" eltűnt, míg a kód megértésének "adója" megnőtt.

b) Errors are not bad — and they're one of the best surfaces. A human-centric API-k simították el a hibákat: elfogadtak uppercase-ot lowercase helyett, vagy többféle boolean értéket (Postgres: true, yes, on, 1). Ez agent-eknél katasztrófa, mert különböző függvények különböző értékeket használnak ugyanarra, és a reviewerek nem tudják értelmezni a kódot. A modern harness-ek debugging közben elolvassák a dokumentációt — "bónuszpont, ha az error message-ben szól is nekik". A homályos, belső hibák viszont spirálba küldik az agent-et, és a rossz utasításkövetés miatt nem tudnak kilábalni. Swerdlow cégének adatai szerint az agent friction 27%-a error-okból származik — a jó error design ugyanolyan fontos, mint a jó dokumentáció.

"In our data, 27% of the friction agents hit comes from errors."

c) "In distribution, not in hallucination." Ha egy API nem egyértelmű, az agent-ek hajlamosak hallucinálni: más, hasonló API-kból vett mintákra építenek. Példaként a name mező: egyes API-k display name-nek, mások full ID-nak, megint mások scoped ID-nak használják. Ha egy agent tíz különböző use-case-ben látja a name-et, öt különböző módon fogja használni — és csak az egyik helyes. A reviewerek, akik évekkel később olvassák a kódot, ugyanazokba az öt értelmezésbe fognak beleesni. A megoldás: specifikus mezőnevek (displayName, slug, externalId), és doc comment, ami rögzíti a helyes értelmezést. "Ezek olyan szavak, amiket az agent valóban megért — nem akad el, nem értelmezi félre."

d) Facts, not feelings. Az API értéke az agent-korszakban az, hogy olyan fact-ot biztosít, amit az agent vagy az emberi csapat belsőleg nem tud reprodukálni: kifizetett számla, elküldött üzenet, provisionált VM. A utility-k ezen túl nagyrészt irrelevánsak — dokumentációval és guide-okkal helyettesíthetők. Swerdlow szkeptikus a legtöbb SDK-val szemben, ami nem csupán a language-specifikus mintákat exponálja (pl. TypeScript hibák erős típusossá alakítása).

4. "Putting this into practice" — a Freestyle példa

A Freestyle sandbox-szolgáltatás: Linux VM-ek nested virtualization-nel, Docker-in-Docker, advanced networking, 8x nagyobb memória-footprint a publikus tier-ekben, full memory snapshots — mind 400 ms alatt provisionálva. A cég korábban egy deklarátív, funkcionális build system-et próbált építeni SDK utility-kkel, ahol a user "kap egy Bun package-t, és nem kell a belső működés miatt aggódnia". Nem működött: sosem volt elég konfigurálható, az agent-ek nem értették és minden létező módon visszaéltek vele, és az absztrakciós rétegek komplexitása vált az onboarding legnehezebb részévé.

A "régi" kód 4 sor helyett 8 sort használt, tele VmSpec, VmBun wrapper-ekkel. Az "új" kód csupasz vm.exec("cd /tmp && /opt/bun/bin/bun add zod") — "just exec", ahogy a Swerdlow írja. Hónapokkal ezelőtt eltávolították az összes komplex SDK package-t, és egy guide-dal helyettesítették, amit az agent a saját use-case-éhez adaptál.

"We used to try to hide as much of the complexity as we could... But we didn't. It was never configurable enough, there were always more questions than answers, agents didn't get it and misused it in every possible way."

5. "In practice in other APIs and SDKs" — tier-list értékelések

Swerdlow konkrét API-kat és SDK-kat rangsorol 🏆/👍/😬/💀 kategóriákban:

Agent framework-ök: - 🏆 Flue Framework — minimális szemantika, pluggable függvények, shared semantics a harness-ek építéséhez. "Az egész agent egy config-ot visszaadó függvény." - 👍 Vercel AI SDK — hasznos shared SDK-szemantika, generateText és streamText tiszta függvények, "one call in, one fact out" elv. - 😬 Mastra — erős scheduling és workflow-k, pluggable típusok, de "heavy-handed and unclear in many places". A Workspace/Filesystem/Sandbox szemantikája "extrém adat-destruktív": egy Docker sandbox FUSE nélkül nem ugyanaz, mint egy SQLite filesystem kombó bare-metal GPU-val. - 💀 Eve — "mintha a Next.js-ből csináltak volna agent framework-öt, király 2016-ra". A skills rendszerük monolitikus és nem programozható; a leíró string dönt a betöltésről build time-ban, nincs hook.

Sandbox API-k: - 🏆 Freestyle (a szerző szerényen: "bias much 🙄") — "az API-k nem csinálnak sokat; azt csinálják, amit mondanak". A box.git.clone utility helyett: "have your AI write a gitClone function" — vm.exec("git clone --depth N URL DIR"). - 👍 E2B — "shows some restraint, not much". A sbx.runCode első argumentuma string, a második egy options bag, ahol a language buried — "textbook példája a human-centric design-nak, ami rossz agent-eknek". - 😬 Daytona — VNC, Git, Docker, Web Terminal, LSP beépítve, mind non-configurable, néhány csendben nem is támogatott. Fél tucat nyelven szállítanak SDK-t, "ami embereknek target-elve" — "ideálisan az agent úgyis megérti az API-kat, hogy ez ne legyen releváns".

6. A "Closing" — mi változik, mi nem

Swerdlow azzal zárja a cikk gerincét, hogy az agent-ekre való építés végre elválik az emberi fejlesztőkre való építéstől. Ami átmegy: jó dokumentáció, világos hibák, usage pattern-ek követése. Ami elveszti a jelentőségét: a kódsorok száma, az onboarding-hibák, a "kötelező olvasás" a produktívvá váláshoz, sőt még a tokenköltség is. A cikk legvégén Swerdlow megjegyzi: "Everything in here wouldn't have been correct with GPT-4.5, so it might not be relevant for GPT-6" — vagyis ez a tanács egy viszonylag szűk ablakra érvényes.

"Building for agents is finally diverging from building for human engineers."

7. Random thoughts — a cikk "outros" része

Swerdlow négy szubjektív, de a cikk szempontjából releváns megjegyzést fűz hozzá:

• Java: utálja írni és editálni, de nem utálja olvasni. A Java legnagyobb hibája (a nehezen kezelhető öröklődés) nem biztos, hogy baj agent-eknek — ők másképp navigálnak a class hierarchiában.
• CLI-k divatja rövid életű lesz. A CLI-k "stopgap az embereknek, akik nem tudják könnyen olvasni az OpenAPI spec-eket, és auth primitíveket, amik nem tartottak lépést". Olyan rendszerek, mint az Auth.md és az Agent Auth, elterjedésével a CLI-k kikopnak: az agent-ek curl-ölhetik a dokumentációt, hívhatják az API-t, és mindent megcsinálhatnak, ami kell. Swerdlow az OpenAPI spec-eket könnyebben introspectálhatónak tartja, mint a CLI-ket.
• MCP Apps kivételt képeznek: a CLI-kkel szemben ezek "újfajta módok az agent chat-tel való interakcióra", és Swerdlow szerint maradandónak tűnnek.
• SDK-k 3 éven belül kikopnak. 2020-ban egy API-hoz SDK-val rendelkezni dealbreaker volt Swerdlow számára (különösen Swift-ben, ahol nem szerette az Alamofire-t). Ma már nem szempont. "Még mindig választanék SDK-t a raw API helyett, de hamarosan az agent fogja ezeket az egyszerű integrációkat vezérelni, és a developer-experience előnye eltűnik."

A cikk inspirálói között említi David Gu-t, Jacob Zwang-ot, Ben Werner-t és Nick Khami-t — "minden dicséretet nekik, panaszt nekem".

A szerző érvelési stratégiája

Swerdlow érvelése az alábbi mintát követi:

1. Személyes hitelesség — "I'm the founder of Freestyle" + konkrét számszerű adat (27% friction errors-ból)
2. Személyes 180-fordulat — nyíltan bevallja, hogy korábbi nézeteit megváltoztatta ("I'm anti-utility now"), ami a hitelességet növeli (emberek nem szoktak 180-at vallani, ha nincs rá okuk)
3. Konkrét before/after kód-példák — a Freestyle "régi" és "új" SDK-ja, a Twilio/Stripe snippet, a Daytona vs. Freestyle git clone példa
4. Tier-list más API-król — konkrét 🏆/👍/😬/💀 rangsorok, ami Swerdlow szubjektív véleménye, de a részletes indoklás miatt review-zható
5. Kritikus disclaimer — "this might not be relevant for GPT-6", ami a paradigmaváltás valós ideiglenességét ismeri el

Összegzés — a legfontosabb 5 takeaway

1. Defaults are bad for agents. Az explicitség olcsó lett, az agent-ek el tudják olvasni a dokumentációt és kitöltik a mezőket. A hosszú, specifikus nevek (displayName, slug, externalId) megakadályozzák a hallucinációt és a 5-féle értelmezést.
2. Errors are the best surface — if precise. Az agent-ek szó szerint követik az utasításokat, és a homályos hibák spirálba küldik őket. A cég 27%-os friction-adata konkrét üzleti érv.
3. Facts over feelings (utilities). Az API értéke a tény (kifizetett számla, elküldött üzenet), nem a utility. A legtöbb SDK wrapper felesleges, ha az agent vm.exec() szintű primitívekkel mindent meg tud csinálni.
4. A Freestyle-példa: a "just exec" győz. A cég eltávolította a komplex SDK-package-eket és egy guide-dal helyettesítette, amit az agent adaptál. A git clone függvényt az AI írja meg, nem a platform szállítja.
5. A 3 éves SDK-párhuzam. Ahogy a 2016-os CLI-k divatja kikopik (Auth.md, Agent Auth), az SDK-k is kikopnak, ahogy az agent-ek egyre több integrációt vezérelnek közvetlenül. A MCP Apps maradnak, mert újfajta interakciót adnak.

Forrás

• Cikk: Designing APIs for Agents — Ben Swerdlow
• URL: https://www.freestyle.sh/blog/opinion/designing-apis-for-agents
• Publikálva: 2026-07-09
• Szerző: Ben Swerdlow (Freestyle founder/CEO)
• Hossz: 13 min read (~3000 szó)
• Inspirációk a cikkhez: David Gu, Jacob Zwang, Ben Werner, Nick Khami
• Eredeti nyelv: angol → magyar (Henky-pipeline, egyszerűsített article pipeline, 2026-07-20)