Dizajn: Slučajevi upotrebe i alati
Na ovoj stranici
Lekcija je ponovno napisana 3. studenog 2026. na temelju OpenAI-jevih stranica dokumentacije Brainstorm plugin use cases i Define tools. Prethodna lekcija instalirala je nepostojeći paket
@openai/apps-sdki manifestchatgpt-app.json; instalacija stvarnih alata (službeni MCP SDK-ovi) odvija se u Lekciji 4. Izvori: Brainstorm plugin use cases · Define tools.
Kreni od očekivanja, a ne od API-ja
OpenAI-jeva dokumentacija savjetuje da počneš graditi dodatak prije nego što napišeš ijednu liniju koda: tako da navedeš što će ljudi od njega očekivati. Naziv dodatka, opis, vještine, alati i proizvod na koji se nadovezuje – sve to stvara očekivanja; tvoja implementacija mora ih ispuniti ili imati namjeran razlog zašto to ne čini.
Zamisli nekoga tko je instalirao tvoj dodatak bez čitanja dokumentacije. Što će ga pitati da učini? Da bi to saznao, osloni se na zadatke koje tvoji korisnici već obavljaju u tvom proizvodu, na zahtjeve za podršku, upite za pretraživanje, zahtjeve za nove funkcije, rječnik koji koriste i privremena rješenja koja ih prisiljavaju da kopiraju podatke iz jednog alata u drugi. Zabilježi izravne zahtjeve koji imenuju dodatak i neizravne zahtjeve koji navode samo cilj: dodatak za upravljanje projektima mora jednako dobro obraditi „Prikaži Acme ploču za lansiranje“ kao i „Što koči lansiranje?“.
Nemoj ograničiti ovaj popis samo na ono što tvoj API već radi. Prvo navedi očekivanja, a zatim ih usporedi s onim što možeš sigurno i pouzdano pružiti.
Popis slučajeva upotrebe
Za svaki slučaj upotrebe OpenAI preporučuje odgovoriti na sedam pitanja:
| Polje | Pitanje |
|---|---|
| Cilj | Što osoba pokušava postići? |
| Primjeri zahtjeva | Kako bi to formulirali, izravno ili neizravno? |
| Očekivani ishod | Što bi interakciju učinilo uspješnom? |
| Potreban kontekst | Koje su informacije, pristup računu ili prethodno stanje potrebni? |
| Mogućnost | Je li vještina dovoljna ili je potreban MCP alat? |
| Granica sigurnosti | Može li ovo otkriti podatke, modificirati stanje, potrošiti novac ili utjecati na treću stranu? |
| Odluka | Prva verzija, kasnija verzija ili namjerno isključenje? |
Grupiraj zahtjeve koji dijele isti cilj: „Navedi moje otvorene zadatke“, „Što moram učiniti danas?“ i „Prikaži zakašnjele poslove“ vjerojatno pripadaju istom slučaju upotrebe pregleda zadataka, ali s različitim filtrima.
Zatim provjeri pokrivenost. Svaki odabrani slučaj upotrebe mora imati potpun put od zahtjeva do rezultata; operacije pisanja moraju uključivati autorizaciju i potvrdu; a dodatak mora znati kako reći što ne radi, nudeći pritom koristan sljedeći korak. Dodatak koji ti omogućuje stvaranje projekata, ali ne i njihovo nabrajanje, pregled ili uređivanje, obećava više nego što isporučuje: ili ga dovrši ili suzi njegovu pozicioniranost.
Isključi i dokumentiraj to
Ne moraš implementirati sve, ali svako veće isključenje zaslužuje razlog: neprihvatljiv rizik za sigurnost ili privatnost, API koji to ne može pouzdano podržati, neprovjerive dozvole, zavaravajući rezultati zbog nedostatka informacija ili opseg prve verzije jasno naveden u popisu dodataka. Zabilježi ove odluke: one informiraju ograničenja vještina, opise alata, odbijanja, testove i tekst javnog popisa.
Od slučajeva upotrebe do alata
Alat mora služiti korisničkom cilju. Nemoj samo kopirati svoj interni API kakav jest. Za svaki odabrani slučaj upotrebe napiši očekivani ishod, navedi potrebne informacije, identificiraj čitanja, pisanja i vanjske radnje, grupiraj ono što čini koherentnu radnju – i odvoji ono što se razlikuje po dozvolama, riziku ili potrebi za potvrdom.
OpenAI-jev primjer za dodatak za projekte:
list_projectsza pronalaženje projekata;get_projectza ispitivanje jednog projekta;create_projectza stvaranje novog;update_projectza modificiranje detalja;archive_projectza promjenu stanja s visokim posljedicama.
Čitanja i pisanja su odvojeni kako bi model i korisnik mogli razlikovati konzultacije od modificiranja.
Ugovor svakog alata
| Polje | Definicija |
|---|---|
| Naziv | Stabilan identifikator usmjeren na radnju |
| Naslov | Sažeta, ljudima čitljiva radnja |
| Opis | Korisnikov cilj i uvjeti koji bi trebali pokrenuti alat |
| Shema ulaza | Obavezni i opcionalni parametri, vrste, dopuštene vrijednosti, ograničenja |
| Shema izlaza | Strukturirana polja koja model može pregledati i ponovno upotrijebiti |
| Autorizacija | Račun, uloga ili pristup koje poslužitelj mora provjeriti |
| Nuspojave | Podaci ili vanjsko stanje koje alat može modificirati |
| Neuspjesi | Pogreške koje model može objasniti ili od kojih se može oporaviti |
Tri pravila dopunjuju ovu tablicu. Eksplicitni ulazi: nemoj se oslanjati na model da pogodi ID ili opseg računa. Ponovno upotrebljivi izlazi: vrati stabilne ID-ove i dovoljno informacija za sljedeći poziv. Čisti izlazi: bez tajni, pristupnih tokena, interne dijagnostike ili nepotrebnih osobnih podataka.
Opisi napisani da budu odabrani
Model odabire alate na temelju njihovog opisa: opiši korisnikovu namjeru, a ne implementaciju. Dobar opis govori što alat radi, kada ga koristiti, kako se razlikuje od susjednih alata i koja su njegova ograničenja ili preduvjeti. Izbjegavaj one koji ponavljaju naziv alata ili koriste interni žargon koji tvoji korisnici ne poznaju.
Sigurnosne napomene
Svaki alat nosi napomene postavljene na temelju njegovog stvarnog ponašanja:
readOnlyHintjetruesamo ako alat ne može modificirati nikakvo stanje;destructiveHintjetrueako alat može proizvesti nepovratan ili teško poništiv rezultat;openWorldHintjetrueako alat pristupa javnom internetu ili otvorenim vanjskim entitetima, čak i ako je samo za čitanje, poput web pretraživanja. Privatni, ograničeni račun ili radni prostor nije „otvoren“ samo zato što je hostiran negdje drugdje.
Napomene pomažu ChatGPT-u i Codexu da odaberu odgovarajuću razinu potvrde, ali ne zamjenjuju autorizaciju na strani poslužitelja, validaciju ulaza ili potvrdu za važne radnje.
Plan koji služi kao plan testiranja
Zadrži popis i plan alata: oni postaju tvoj popis za provjeru. Dodaj izravne, neizravne, granične i izvan-opsega zahtjeve te provjeri ponaša li se gotovi dodatak kako se očekuje za svaki od njih. Također potraži alate koji ne služe nijednom dokumentiranom slučaju upotrebe, nedostajuća čitanja prije pisanja i opise koji su previše slični i koji bi mogli zbuniti model.
Ključne točke
- Kreni od onoga što će korisnici očekivati, a zatim usporedi s onim što možeš sigurno pružiti
- Popis od sedam pitanja po slučaju upotrebe, uključujući namjerna isključenja
- Jedan alat po koherentnoj radnji; čitanja i pisanja su odvojeni
- Jedan ugovor po alatu: naziv, naslov, opis, sheme, autorizacija, nuspojave, neuspjesi
- Napomene (
readOnlyHint,destructiveHint,openWorldHint) slijede stvarno ponašanje i ne zamjenjuju autorizaciju