AI agenti rijetko ne uspiju zato što je uputa bila jedna rečenica prekratka. Ne uspiju zato što su sustavi oko njih dizajnirani za čovjeka koji klikće kroz predvidljivo sučelje, dok agent treba promatrati stanje, poduzimati ograničene radnje, oporaviti se od nejasnoća i objasniti što se dogodilo.

Ta razlika mijenja dizajn API-ja. Krajnja točka koja je tehnički ispravna za frontend i dalje može biti loš alat za agenta koji se razvija. API-ji namijenjeni agentima moraju biti eksplicitni, pregledni, sigurni za ponavljanje i dovoljno stabilni da ih model može koristiti bez oslanjanja na slučajno poznavanje pojedinosti implementacije.

Dizajnirajte za radnje, a ne za zaslone

Mnogi API-ji nasljeđuju oblik web-aplikacije: krajnje točke odražavaju obrasce, stranice i tokove korisničkog sučelja. To je razumljivo, ali može stvoriti nezgrapne alate za agenta. Ruta poput POST /checkout može objediniti provjeru valjanosti, plaćanje, rezervaciju zaliha i obavijesti u jednu neprozirnu operaciju. Kada ne uspije, agent ima malo korisnih informacija na temelju kojih može odlučiti o sljedećem potezu.

Umjesto toga, modelirajte smislene poslovne radnje i izložite prijelaze stanja oko njih. API za ispunjenje narudžbi mogao bi ponuditi zasebne mogućnosti za pregled narudžbe, rezervaciju zaliha, izradu pošiljke i otkazivanje neposlane pošiljke. Svaka radnja trebala bi imati jasan preduvjet i vidljiv rezultat.

{
  "order_id": "ord_4821",
  "status": "awaiting_inventory",
  "available_actions": [
    "reserve_inventory",
    "cancel"
  ],
  "blocking_reasons": [
    {
      "code": "INSUFFICIENT_STOCK",
      "sku": "SKU-RED-42",
      "requested": 3,
      "available": 1
    }
  ]
}

Polje available_actions osobito je vrijedno. Sprječava agenta da nagađa koja je operacija valjana u trenutačnom stanju. Također omogućuje backendu da razvija pravila tijeka rada bez potrebe da klijent obrnutim inženjeringom utvrđuje svaki prijelaz.

Učinite stanje razumljivim, a pogreške primjenjivima

Agent ne može pogledati crveni banner i zaključiti namjeru. Potrebni su mu strukturirani odgovori na pogreške koji razlikuju neispravno oblikovan unos, neuspješna poslovna pravila, probleme s autorizacijom i prolazne infrastrukturne kvarove.

Odgovor koji kaže “Unable to process request” slijepa je ulica. Odgovor sa stabilnim kodom pogreške, ljudima čitljivim sažetkom, klasifikacijom ponavljanja i pojedinostima na razini polja daje i agentu i njegovom operateru put naprijed.

{
  "error": {
    "code": "PAYMENT_METHOD_EXPIRED",
    "message": "The selected payment method has expired.",
    "retryable": false,
    "action": "request_updated_payment_method",
    "details": {
      "payment_method_id": "pm_91"
    }
  }
}

Nemojte svaku pogrešku učiniti ponovljivom. Ponovno pokušavanje nakon privremenog isteka vremena baze podataka može imati smisla; ponovno pokušavanje s nevaljanim kodom valute nema. Koristan API tu razliku čini eksplicitnom, dok klijenti i dalje primjenjuju ograničena pravila ponovnih pokušaja s odgodom i zaštitom idempotentnosti.

Idempotentnost je sigurnosna značajka agenta

Agenti djeluju u svijetu neizvjesnog dovršavanja. Mrežni zahtjev može isteći nakon što je poslužitelj već stvorio pošiljku. Proces se može ponovno pokrenuti između primanja odgovora i njegova bilježenja. Model može ponoviti radnju nakon gubitka konteksta.

Za operacije s nuspojavama prihvatite ključ idempotentnosti i pohranite rezultat povezan s tim ključem. Ponavljanje istog zahtjeva trebalo bi vratiti izvorni ishod umjesto stvoriti novu naplatu, tiket, e-poštu ili implementaciju.

POST /shipments
Idempotency-Key: 6a7d4e89-2d77-4cd0-9d23-3d2bdbe15342
Content-Type: application/json

Na backendu pažljivo odredite opseg ključa: obično prema zakupniku, operaciji i ključu. Uz dovršeni odgovor pohranite otisak zahtjeva. Ako isti ključ stigne s bitno drukčijim unosom, vratite sukob umjesto da tiho prihvatite dvosmisleni duplikat.

U PHP-u to često znači tretirati zapis idempotentnosti kao dio iste transakcijske granice kao i poslovnu operaciju. Ako se redak pošiljke potvrdi, a zapis idempotentnosti ne, problem ponovnog pokušaja ostaje. Ako je uključen vanjski rad, upotrijebite obrazac outbox umjesto pokušaja da pružatelja e-pošte ili pristupnik za plaćanje učinite dijelom transakcije baze podataka.

Odvojite brze naredbe od sporog rada

Dugotrajni rad neugodan je za preglednike i nepouzdan za agente. Generiranje izvješća, skupni uvozi, obrada videozapisa i višekoračno provisioniranje obično bi trebali postati asinkroni poslovi.

Krajnja točka naredbe može provjeriti zahtjev, stvoriti trajni posao i brzo vratiti odgovor. Agent zatim može anketirati resurs ili primiti povratni poziv putem integracijskog sloja dizajniranog za tu svrhu.

{
  "job_id": "job_18f0",
  "status": "queued",
  "status_url": "/jobs/job_18f0"
}

Status posla trebao bi pružati više informacija od queued, running i failed. Uključite napredak tamo gdje ima smisla, vremenske oznake završetka, sažet kod neuspjeha i poveznice na stvorene resurse. Izbjegavajte izlaganje sirovih iznimki radnika kao javnog ugovora; previše se lako mijenjaju i mogu otkriti pojedinosti implementacije.

Koristite sheme kao granice proizvoda

Tipizirani ugovori zahtjeva i odgovora nisu birokracija. Oni su zajednički jezik između agenta, njegova orkestratora, backend usluga i ljudskih održavatelja. Shema bi trebala dokumentirati obavezna polja, formate, nabrajanja, vrijednosti koje mogu biti null, ponašanje paginacije i primjere odgovora na neuspjeh.

Budite konzervativni pri izmjeni objavljenog ugovora. Dodavanje neobaveznog polja općenito je izvedivo. Preimenovanje statusa, promjena značenja logičke vrijednosti ili pretvaranje niza u objekt mogu pokvariti agenta na načine koji izgledaju kao neuspjesi rezoniranja.

• Preferirajte eksplicitno verzioniranje kada je semantički prekid neizbježan.
• Kao ulaze za mutacije koristite stabilne identifikatore, a ne prikazna imena.
• Podijelite zbirke na stranice i osigurajte deterministički redoslijed.
• Izložite vremenske oznake u dokumentiranom, dosljednom formatu.
• Namjerno zastarijevajte, uz put migracije umjesto iznenadnog uklanjanja.

Ograničite ovlasti blizu podataka

Upute u promptu korisne su, ali nisu sustav autorizacije. API mora provoditi granice zakupnika, vlasništvo, dopuštenja uloga, ograničenja stope i pravila specifična za operacije. Agent bi trebao dobiti najmanju mogućnost potrebnu za svoj trenutačni zadatak.

To je još važnije kada agent može pozivati široke krajnje točke za pretraživanje ili administraciju. Praktičan token koji “može sve” pretvara svaku pogrešku ubrizgavanja prompta u sigurnosni incident. Uski opsezi, provjere na razini resursa, zapisnici audita i operacije koje zahtijevaju odobrenje trajnije su kontrole.

Za radnje s velikim utjecajem razmotrite dvokoračni dizajn: stvorite predloženu promjenu, zatim je izvršite zasebnom krajnjom točkom za odobrenje ili potvrdu. Time se čuva automatizacija, a nepovratne odluke čine vidljivima i podložnima pregledu.

Vidljivost je dio sučelja

Kada agent poduzme radnju, operateri trebaju moći rekonstruirati lanac događaja. Vratite identifikatore zahtjeva ili operacije, propagirajte korelacijske ID-jeve kroz usluge i bilježite strukturirane događaje oko promjena stanja. Cilj nije zabilježiti svaki prompt. Cilj je odgovoriti na praktična pitanja: što je pokušano, pod čijom ovlašću, nad kojim resursom i što se promijenilo?

Metrike bi trebale slijediti isto načelo. Pratite klase pogrešaka, latenciju reda čekanja, ponavljanja idempotentnosti, odbijanja autorizacije i neuspješne prijelaze stanja. Ti signali otkrivaju je li problem ponašanje modela, nejasan ugovor, problem kapaciteta ili pokvarena ovisnost.

Izgradite API-je koji olakšavaju siguran put

Najjači API za agente nije onaj s najviše krajnjih točaka. To je onaj koji ispravno ponašanje čini očitim, a nesigurno ponašanje teškim: eksplicitno stanje, jasne radnje, trajna ponavljanja, uska dopuštenja, stabilni ugovori i korisne informacije o neuspjehu.

Promptovi će se mijenjati. Modeli će se poboljšavati. Orkestracijski okviri dolazit će i odlazit će. Dobro dizajniran backend ostaje stabilan dio sustava, pretvarajući neizvjesnu namjeru vođenu jezikom u kontrolirane, vidljive poslovne operacije.