Upravljanje orodja za agente prek prehoda AI API: obsegi, odobritve, proračuni in revizijske sledi
Praktična referenčna arhitektura za upravljanje orodij agentov prek prehoda AI API: registri orodij, ključi z obsegom, vrata za odobritev, proračuni za posamezna orodja, seznami dovoljenih MCP in združene revizijske sledi modela/orodja.
Tveganje agenta ni več omejeno na poziv modela. Produkcijski agent lahko preišče notranje datoteke, poizveduje po zapisih strank, pokliče strežnik MCP, izvede kodo, odpre brskalnik, pošlje e-pošto, posodobi CRM ali sproži potek dela za obračunavanje. Vprašanje upravljanja postane: kateremu uporabniku, ključu, modelu, agentu in orodju je bilo dovoljeno izvesti katero dejanje, s kakšnim proračunom, revizijsko sledjo in potjo povrnitve?
Če vsaka ekipa obravnava dostop do orodij znotraj lastne kode SDK, postane pravilnik razpršen po spremenljivkah okolja, nadzornih ploščah ponudnika, vmesni programski opremi aplikacij in nedokumentiranih strežnikih MCP. Varnejši vzorec je obravnavati izvajanje orodja agenta kot problem nadzorne ravnine in ga uveljaviti prek prehoda AI API ali standardnega ovoja izvajanja orodja, ki ga mora uporabljati vsak agent.
Ta članek ločuje dejstva, priporočila in napovedi. Dejstva so povzeta iz trenutnih javnih smernic: Top 10 aplikacij za LLM OWASP vključuje tveganja, kot so razkritje občutljivih informacij, ranljivosti dobavne verige in pretirana agencija; Generativni profil umetne inteligence NIST za okvir upravljanja tveganja umetne inteligence poudarja kartiranje, merjenje in upravljanje generativnih tveganj umetne inteligence; Smernice agenta OpenAI priporočajo oceno tveganja orodja glede na dostop za branje/pisanje, reverzibilnost, dovoljenja in finančni učinek; in navodila za avtorizacijo MCP uporabljajo koncepte avtorizacije z omejenim obsegom za občutljive vire in operacije. Spodnja priporočila so vzorci implementacije, ne univerzalne zahteve.
Težava z bralnikom: zamenjujeta se dostop do modela in dostop do orodja
V mnogih zgodnjih aplikacijah LLM je ključ API odgovoril na eno osnovno vprašanje: ali lahko ta storitev kliče model? Agenti naredijo to preveč grobo. Ključ, ki lahko pošilja zaključke klepeta, ne bi smel samodejno izvažati podatkov o strankah, izvajati lupinskih ukazov, objavljati v Slacku, spreminjati vstopnic, brskati po poljubnih spletnih mestih ali pošiljati spremembe plačil.
Sloj upravljanja mora odgovoriti na bolj specifična vprašanja:
- Kateri najemnik, delovni prostor, uporabnik, račun storitve ali stranka preprodajalca je sprožila izvajanje?
- Kateri model, predloga poziva, različica agenta in shema orodja so bili uporabljeni?
- Ali je bilo zahtevano orodje samo za branje, reverzibilno, nepovratno, zunanje, finančno ali privilegirano?
- Ali je imel vlagatelj zahteve zahtevani obseg?
- Ali je bila odobritev zahtevana, odobrena, zavrnjena, potekla ali zaobšla pravilnik o nujnih primerih?
- Koliko je stalo orodje, kolikokrat je bilo klicano in kakšen kumulativni proračun je ostal?
- Kateri dokazi obstajajo za odpravljanje napak, pregled skladnosti in povrnitev?
Spodnja arhitektura predvideva, da prehod že sprejema klice modela. Izvajanje orodja je nato mogoče usmeriti prek istega prehoda, prek stranske storitve ali prek standardne knjižnice, ki poroča prehodu pred in po vsakem klicu orodja.
Referenčna arhitektura: plast upravljanja orodja na ravni prehoda
Praktični sistem upravljanja agentov ima sedem komponent:
- Register orodij: avtoritativni seznam odobrenih orodij, strežnikov MCP, gostujočih funkcij, lokalnih orodij za izvajanje in internih API-jev.
- Identiteta in sloj ključa: ključi prehoda, uporabniki, najemniki, storitveni računi, ekipe in stranke prodajnih posrednikov.
- Mehanizam obsega: preverjanja pravilnika, ki odločajo, ali lahko ključ ali uporabnik prikliče določeno zmožnost orodja.
- Klasifikator tveganja: metapodatki, ki opisujejo radij eksplozije, občutljivost podatkov, reverzibilnost, zunanji vpliv in izpostavljenost stroškom.
- Potek dela odobritve: človeška ali sistemska odobritev za dejanja z visokim tveganjem pred izvedbo.
- Knjiga omejitev proračuna in stopnje: omejitve na orodje in agenta, ne le omejitve žetona na model.
- Shramba za revizijo in sledenje: združeni zapisi za klice modelov, klice orodij, odobritve, napake in rezultate.
Pomembna oblikovalska odločitev je, da prehod postane točka odločanja o politiki, tudi če se dejansko orodje izvaja drugje. Na primer, orodje brskalnika se lahko izvaja v delavcu v peskovniku, pisanje CRM pa se lahko izvaja znotraj notranje storitve. Prehod še vedno oceni, ali je klic dovoljen, zabeleži odločitev, sledi stroškom in vrne podpisano avtorizacijsko odločitev ali zavrnitev.
1. korak: Zgradite osrednji register orodij
Register orodij je inventar, ki preprečuje, da bi »zmožnost neznanega agenta« postala privzeta. Vsako orodje mora imeti lastnika, stopnjo tveganja in operativne metapodatke. Najmanjši zapis v registru je lahko videti takole:
{
"tool_id": "crm.create_ticket",
"display_name": "Ustvari vstopnico za podporo CRM",
"owner_team": "podpora-avtomatizacija",
"vrsta_izvedbe": "notranji_api",
"server_url": "https://tools.internal.example/crm",
"allowed_tenants": ["enterprise", "support"],"allowed_models": ["splošno-veliko", "splošno-hitro"],
"risk_tier": "reverzibilno_pisanje",
"data_classification": "metapodatki_stranke",
"required_scopes": ["tool:crm.create_ticket"],
"approval_policy": "ni_potrebno_pod_100_vstopnic_na_dan",
"default_timeout_ms": 8000,
"max_cost_per_call_usd": 0,05,
"max_calls_per_run": 3,
"rollback_owner": "support-ops-oncall",
"retention_policy": "redicted_30_days"
}Za strežnike MCP mora register vključevati tudi URL strežnika, oglaševana orodja, različico sheme, avtorizacijski način, datum zadnjega pregleda in ali so nova orodja privzeto onemogočena. MCP izboljša interoperabilnost, vendar združljivost protokola ni isto kot avtorizacija proizvodnje. Občutljivi viri in operacije še vedno potrebujejo eksplicitne obsege, preverjanja poti in izolacijo najemnikov.
Priporočena polja registra
- Ime orodja, kanonični ID, lastnik in dežurni stik.
- Lokacija izvajanja: orodje gostujočega ponudnika, strežnik MCP, notranji API, delavec brskalnika, izvajalec kode, opravilo čakalne vrste ali lokalno orodje SDK.
- Dovoljeni najemniki, ekipe, uporabniki, različice agentov in profili modelov.
- Klasifikacija podatkov: javni, interni, metapodatki o strankah, vsebina o strankah, skrivnosti, podatki o plačilih, poverilnice, nadzorovani podatki.
- Raven tveganja in reverzibilnost.
- Zahtevani obsegi in politika odobritve.
- Časovne omejitve, omejitve stopnje, največje število klicev na zagon, kumulativni proračun za zagon in najvišja cena na klic.
- Način beleženja: celotna koristna obremenitev je prepovedana, redigirana, zgoščena, vzorčena ali izrecno ohranjena.
- Navodila za povrnitev in pot eskalacije.
2. korak: Ločite obsege modela od obsegov orodij
Ključ produkcijskega prehoda mora izražati, kaj klicatelj lahko naredi. Dostop do modela in orodja morata biti neodvisna. Na primer:
model:klepet
model: vdelave
orodje:docs.search_readonly
orodje:crm.create_ticket
tool:email.send_requires_approval
orodje:billing.refund_blocked
tool:code.execute_blockedTo preprečuje, da bi klepetalni robot z nizkim tveganjem postal pomotoma agent za avtomatizacijo. Podpira tudi predloge vlog:
- Pomočnik za razvijalce: modelni klepet, iskanje dokumentacije, razlaga kode, brez orodij za pisanje v produkciji.
- Podporni bot: iskanje strank, ustvarjanje vstopnic, priprava odgovorov, zahtevana odobritev za zunanja pošiljanja.
- Agent za analitike: poizvedbe v skladišču podatkov samo za branje z omejitvami vrstic, privzeto brez izvozov strank.
- Skrbniški agent: ozke privilegirane operacije, močna odobritev, kratkotrajni ključi, popolna revizija.
- Agent za najemnike prodajnega posrednika: dostop do modela v obsegu najemnika, orodja v obsegu najemnika, zgornje meje proračuna na stranko.
Priporočilo je, da se ne zapre: neznana orodja so zavrnjena, manjkajoči obsegi zavrnejo izvedbo, na novo oglaševana orodja MCP so neaktivna, dokler niso odobrena, lokalna orodja pa morajo uporabljati isti ovoj pravilnika kot gostujoča orodja.
3. korak: Razvrstite orodja po polmeru razstreljevanja
Za vsak klic orodja ni potrebna človeška odobritev. Upravljanje mora biti sorazmerno s tveganjem. Uporaben klasifikacijski model je:
Ta razvrstitev mora biti vidna pri pregledu kode in v skrbniškem uporabniškem vmesniku. Samo opisi orodij niso dovolj, ker lahko agenti opise obravnavajo kot navodila. Mehanizem pravilnika bi se moral zanašati na metapodatke in obsege registra, ne le na imena orodij v naravnem jeziku.
4. korak: dodajte vrata za odobritev za dejanja z visokim tveganjem
Odobritev mora biti usmerjena. Če vsak klic orodja zahteva osebo, agent postane neuporaben. Če noben klic orodja ne zahteva odobritve, lahko sistem odobri pretirano posredovanje.
Običajen potek odobritve:
- Agent zahteva klic orodja s strukturiranimi argumenti.
- Prehod oceni identiteto, obseg, stopnjo tveganja, proračun in politiko.
- Če je potrebna odobritev, prehod namesto izvedbe orodja vrne čakajoč dogodek odobritve.
- Aplikacija prikaže predogled uporabniku ali pošlje obvestilo o operaciji kanalu za odobritev.
- Odobritelj lahko odobri, zavrne, uredi argumente, če pravilnik dovoljuje, ali zahteva pojasnilo.
- Prehod zabeleži odločitev in izvede samo odobreno različico.
Koristna vsebina odobritve mora prikazovati dejanje v človeškem smislu, ne le v neobdelanem JSON:
{
"approval_id": "appr_123",
"agent_run_id": "run_456",
"requested_by_user": "uporabnik_789",
"tool_id": "email.send",
"risk_tier": "zunanja_komunikacija",
"summary": "Pošlji odgovor na [email protected] o vstopnici #4812",
"redacted_arguments": {
"za": "[email protected]",
"subject": "Posodobitev na vstopnici #4812",
"body_hash": "sha256:..."
},
"expires_at": "2026-08-09T12:30:00Z"
}Odobritev je najbolj uporabna za zunanjo komunikacijo, finančna dejanja, nepovratna pisanja, privilegirano administracijo in širok izvoz podatkov. Običajno ni potreben za iskanje majhne količine javne dokumentacije.
5. korak: Sledite proračunom za posamezno orodje in omejitvam stopnje
Proračuni žetonov niso dovolj. Poceni model lahko sproži draga iskanja, seje brskalnika, izvajanje kode, klice API-ja tretjih oseb ali dolge zanke orodja. Prehod mora slediti vsaj štirim števcem:
- Število klicev na orodje: največje število klicev na zagon, uporabnika, najemnika in časovno okno.
- Stroški na orodje: neposredni stroški tretjih oseb, stroški brskalnika/izvajalnega časa, stroški iskanja ali interna ocena povratne bremenitve.
- Kumulativni stroški delovanja agenta: žetoni modela in stroški orodja.
- Globina zanke: največje število ponovitev model-orodje-model.
Ko je dosežena omejitev, se mora prehod izogibati tihi trdi napaki, kadar je to mogoče. Varnejši vzorci degradacije vključujejo vrnitev povzetka napredka, prošnjo za odobritev nadaljevanja, znižanje globine iskanja, čakalno vrsto opravila v ozadju ali preklop v način samo za branje. Trdna zavrnitev je še vedno primerna za blokirana orodja, manjkajoče obsege, neznane zmožnosti MCP in nevarna dejanja.
6. korak: Združite telemetrijo modela in orodja v en revizijski zapis
Odpravljanje napak agenta ne uspe, če so dnevniki modela na enem mestu, dnevniki orodij pa nekje drugje. Revizijski zapis mora povezovati celotno verigo:
- Najemnik, delovni prostor, uporabnik, storitveni račun in ključ prehoda.
- ID agenta, različica agenta, različica predloge poziva in ID modela.
- Ime orodja, različica registra, URL strežnika ali okolje izvajanja in zgoščena vrednost sheme.
- Zgoščena vrednost vnosa orodja ali redigirani vnos, privzeto nikoli neobdelane občutljive vsebine.
- Status odobritve, identiteta odobritelja, časovni žig odobritve in zgoščena vrednost odobrenega argumenta.
- Zakasnitev, ponovni poskusi, napake ponudnika, napake orodja, stroški žetona, stroški orodja in končni rezultat.
- Sklic na povrnitev, če je dejanje spremenilo stanje.
Dokumentacija za sledenje SDK agentov OpenAI vključuje sledi za generacije LLM, klice orodij, predaje, zaščitne ograje in dogodke po meri, ki podpirajo širše načelo opazovanja: sledi agentov morajo vključevati dejavnost orodij, ne le uporabo žetonov in zakasnitve. Vendar pa en sam cevovod SDK morda ne bo pokrival vsakega gostujočega orodja, lokalne izvedbene poti ali notranjega API-ja. Revizija na ravni prehoda pomaga normalizirati zapise med ponudniki in ogrodji.
Zasebnost je pomembna. Podrobni dnevniki izboljšajo odpravljanje napak in pregled skladnosti, vendar lahko neobdelani pozivi in zadrževanje koristne obremenitve orodja povzročijo novo varnostno odgovornost. Uredite ali zgostite vnose, ki vsebujejo skrivnosti, poverilnice, podatke o plačilu, osebne podatke ali zaščitene dokumente. Shranjujte neobdelane tovore samo v skladu z izrecno politiko hrambe, nadzorom dostopa in pravili za brisanje.
7. korak: Obravnavajte strežnike MCP in orodja tretjih oseb kot odvisnosti od dobavne verige
Strežniki MCP in orodja tretjih oseb bi morali iti skozi isti postopek pregleda kot knjižnice, webhooki in odvisnosti od infrastrukture. Priporočeni kontrolniki vključujejo:
- Vzdržujte dovoljeni seznam odobrenih strežnikov MCP in izvorov orodij.
- Pripnite različice, kjer je to mogoče, in zabeležite zgoščene sheme.
- Zahtevajte lastnika za vsak strežnik in orodje z visokim tveganjem.
- Preglejte imena orodij, opise, sheme in zahtevke za dovoljenja, preden jih omogočite.
- Onemogočite novo dodana orodja, dokler jih ne pregledate.
- Preverite zahtevane obsege na pot ali zmogljivost.
- Ločite poverilnice najemnika in se izognite skupni žetoni med strankami.
- Izvajajte nezaupljiva ali visoko tvegana orodja v peskovnikih z omejitvami omrežja in datotečnega sistema.
Dejstvo, da je orodje izpostavljeno prek standardnega protokola, še ne pomeni, da je varno. Plast upravljanja še vedno potrebuje najmanj privilegijev, izrecno avtorizacijo, nadzor različic in revizijsko sposobnost.
Kontrolni seznam za implementacijo
Oblikovanje pravilnika
- Določite predloge vlog za običajne uporabnike posrednikov in storitvene račune.
- Ustvarite ločena področja za klice modela in klice orodij.
- Razvrstite orodja po občutljivosti podatkov, reverzibilnosti, zunanjem vplivu, finančnem vplivu in ravni privilegijev.
- Nastavite privzeto zavrnitev za neznana orodja in manjkajoče obsege.
- Določite pravila odobritve samo za dejanja z visokim tveganjem.
Uveljavljanje prehoda
- Zahtevajte, da vsak agent kliče orodja prek prehoda ali podpisanega ovoja pravilnika.
- Preverite najemnika, uporabnika, ključ, agenta, model, orodje, obseg, proračun in stanje odobritve pred izvedbo.
- Uveljavi največjo globino klica orodja in kumulativne stroške izvajanja.
- Zabeležite različico registra orodja in zgoščeno vrednost sheme za vsak klic.
- Napaka zaprta, ko mehanizem pravilnika ne more sprejeti odločitve.
Revizija in poslovanje
- Združite klice modela in klice orodij pod enim ID-jem sledenja ali izvajanja agenta.
- Privzeto popravi ali zgosti občutljive vnose orodja.
- Hranite dokaze o odobritvi s končnim zapisom o izvedbi.
- Skrbnikom razkrijte analizo stroškov na orodje in omejitev stopnje.
- Lastniki povrnitve dokumentov za orodja, ki spreminjajo stanje.
Pričakovani kompromisi
Doslednost v primerjavi s prizadevanji za integracijo. Upravljanje na ravni prehoda omogoča dosledno uveljavljanje v vseh modelih, SDK-jih in skupinah. Cena je sprejetje: razvijalci morajo usmerjati izvajanje orodij po odobreni poti, namesto da kličejo orodja neposredno iz kode aplikacije.
Najmanj privilegijev v primerjavi s kompleksnostjo pravilnika. Drobno zrnati obsegi zmanjšajo radij eksplozije, vendar zahtevajo predloge, pravila poimenovanja in redno čiščenje. Brez predlog lahko skupine podelijo dovoljenja za hitrejše premikanje.
Odobritev v primerjavi z avtonomijo. Človeška odobritev zmanjša tveganje za nepopravljiva dejanja, vendar doda zakasnitev. Uporabite odobritve za orodja z visokim tveganjem, ne za vsako iskanje ali iskanje.
Pregledljivost v primerjavi z izpostavljenostjo podatkov. Bogati dnevniki pomagajo pri odzivanju na incidente in odpravljanju napak. Neobdelano beleženje tovora lahko razkrije skrivnosti in osebne podatke. Redakcija, zgoščevanje, nastavljivo hranjenje in pregled dostopa niso neobvezne podrobnosti.
Trde omejitve v primerjavi z dokončanjem nalog. Omejitve stroškov posameznega orodja preprečujejo pobegle agente. Prav tako lahko prekinejo zakonito dolgotrajno delo. Navedite poti nadaljevanja, kot so odobritev za nadaljevanje, čakalne vrste v ozadju ali povzeti delni rezultati.
Napovedi: kam pelje ta vzorec
Napoved: upravljanje agentov bo postalo bolj osredotočeno na identiteto. Ekipe bodo manj pogosto spraševale, "kateri model je ta uporabil?" in pogosteje "katera overjena oseba ali storitev je dovolila to dejanje orodja?"
Napoved: registri orodij bodo postali običajni kot registri modelov. Ker se strežniki MCP, notranji API-ji in gostujoča orodja množijo, bodo produkcijske ekipe potrebovale popis dovoljenih zmogljivosti, lastnikov, shem in ravni tveganja.
Napoved: upravljanje stroškov se bo premaknilo s poročanja samo z žetoni na poročanje na ravni dejanj. Najdražji del zagona agenta je lahko iskanje, avtomatizacija brskalnika, izvajanje kode ali API-ji tretjih oseb in ne sam klic modela.
Dejanski sklep
Začnite z enim pravilom: ključ modela ni ključ orodja. Nato gradite navzven. Ustvarite register odobrenih orodij, dodelite lastnike in stopnje tveganja, zahtevajte izrecne obsege, dodajte odobritve samo, če ima dejanje pomemben radij eksplozije, uveljavite proračune za posamezno orodje ter združite dogodke modela in orodja v eno revizijsko sled.
Cilj ni narediti agente nemočne. Cilj je, da je njihova moč berljiva, omejena, reverzibilna, kjer je to mogoče, in odgovorna. To je praktična podlaga za upravljanje timskega API-ja, ko se agenti premaknejo od odgovarjanja na vprašanja k dejanjem.