Ügynöki eszköz irányítása AI API-átjárón keresztül: hatókörök, jóváhagyások, költségvetések és ellenőrzési nyomvonalak
Praktikus referenciaarchitektúra az ügynökeszközök irányításához AI API-átjárón keresztül: eszköznyilvántartások, hatókörű kulcsok, jóváhagyási kapuk, eszközenkénti költségvetések, MCP engedélyezési listák és egyesített modell/eszköz ellenőrzési nyomvonalak.
Az ügynökkockázat már nem korlátozódik a modell promptjára. Az éles ügynök kereshet belső fájlokban, lekérdezhet ügyfélrekordokat, hívhat egy MCP-kiszolgálót, végrehajthat kódot, megnyithat egy böngészőt, e-mailt küldhet, frissítheti a CRM-et, vagy elindíthat egy számlázási munkafolyamatot. Az irányítási kérdés a következő: melyik felhasználó, kulcs, modell, ügynök és eszköz milyen műveletet hajthatott végre, milyen költségvetéssel, ellenőrzési nyomvonallal és visszaállítási útvonallal?
Ha minden csapat a saját SDK-kódján belül kezeli az eszközhozzáférést, a házirend szétszórva lesz a környezeti változók, a szolgáltatói irányítópultok, az alkalmazások köztes szoftverei és a nem dokumentált MCP-kiszolgálók között. Biztonságosabb minta, ha az ügynökeszköz-végrehajtást vezérlősík-problémaként kezeljük, és egy AI API-átjárón vagy egy szabványos eszköz-végrehajtási burkolón keresztül kényszerítjük ki, amelyet minden ügynöknek használnia kell.
Ez a cikk tényeket, ajánlásokat és előrejelzéseket különít el. A tények a jelenlegi nyilvános útmutatásból származnak: az OWASP LLM Application Top 10-je olyan kockázatokat tartalmaz, mint az érzékeny információk nyilvánosságra hozatala, az ellátási lánc sebezhetősége és a túlzott ügynökség; A NIST generatív AI-profilja az AI kockázatkezelési keretrendszerhez a generatív mesterségesintelligencia-kockázatok feltérképezésére, mérésére és kezelésére helyezi a hangsúlyt; Az OpenAI ügynöki útmutatása azt javasolja, hogy értékelje az eszközök kockázatát az olvasási/írási hozzáférés, a visszafordíthatóság, az engedélyek és a pénzügyi hatás alapján; és az MCP engedélyezési útmutató hatókörű engedélyezési koncepciókat használ az érzékeny erőforrásokhoz és műveletekhez. Az alábbi ajánlások megvalósítási minták, nem általános követelmények.
Az olvasó probléma: a modellelérés és az eszköz-hozzáférés összekeveredik
Sok korai LLM-alkalmazásban egy API-kulcs egy alapvető kérdésre adott választ: hívhat-e ez a szolgáltatás modellt? Az ügynökök ezt túl durvává teszik. A csevegési befejezéseket küldeni képes kulcs nem képes automatikusan exportálni az ügyféladatokat, futtatni shell-parancsokat, közzétenni a Slackben, módosítani a jegyeket, böngészni tetszőleges webhelyeken, vagy beküldeni fizetési módosításokat.
Az irányítási rétegnek konkrétabb kérdésekre kell válaszolnia:
- Melyik bérlő, munkaterület, felhasználó, szolgáltatásfiók vagy viszonteladói ügyfél kezdeményezte a futtatást?
- Melyik modellt, prompt sablont, ügynökverziót és eszközsémát használtak?
- A kért eszköz írásvédett, visszafordítható, visszafordíthatatlan, külső, pénzügyi vagy privilegizált volt?
- A kérelmező rendelkezett a szükséges hatókörrel?
- A vészhelyzeti szabályzat megköveteli, megadta, megtagadta, lejárt vagy megkerülte a jóváhagyást?
- Mibe került az eszköz, hányszor hívták meg, és mennyi maradt a halmozott költségvetés?
- Milyen bizonyítékok állnak rendelkezésre a hibakeresésre, a megfelelőség ellenőrzésére és a visszaállításra?
Az alábbi architektúra feltételezi, hogy az átjáró már fogad modellhívásokat. A szerszámvégrehajtás ezután ugyanazon az átjárón, egy oldalkocsi-szolgáltatáson vagy egy szabványos könyvtáron keresztül irányítható, amely minden szerszámhívás előtt és után jelentést tesz az átjárónak.
Referenciaarchitektúra: átjáró szintű eszközirányítási réteg
A gyakorlati ügynökirányítási rendszer hét összetevőből áll:
- Eszköz-nyilvántartás: a jóváhagyott eszközök, MCP-kiszolgálók, tárolt funkciók, helyi végrehajtási eszközök és belső API-k hiteles listája.
- Identitás és kulcsréteg: átjárókulcsok, felhasználók, bérlők, szolgáltatásfiókok, csapatok és viszonteladói ügyfelek.
- Hatókör motor: házirend-ellenőrzések, amelyek eldöntik, hogy egy kulcs vagy felhasználó meghívhat-e egy adott eszközfunkciót.
- Kockázatbesoroló: metaadatok, amelyek leírják a robbanás sugarát, az adatérzékenységet, a visszafordíthatóságot, a külső hatásokat és a költségek kitettségét.
- Jóváhagyási munkafolyamat: emberi vagy rendszer jóváhagyása magas kockázatú műveletekhez a végrehajtás előtt.
- Költségkeret és kamatkorlát főkönyve: szerszámonkénti és ügynökönkénti korlátok, nem csak modellenkénti token-korlátok.
- Audit és nyomkövetési tár: modellhívások, eszközhívások, jóváhagyások, hibák és eredmények egyesített rekordjai.
A fontos tervezési döntés az, hogy az átjáró legyen a politikai döntési pont akkor is, ha a tényleges eszköz máshol fut. Például egy böngészőeszköz végrehajtható egy sandbox-munkásban, és egy CRM-írás egy belső szolgáltatáson belül. Az átjáró továbbra is kiértékeli, hogy a hívás engedélyezett-e, rögzíti a döntést, nyomon követi a költségeket, és aláírt engedélyezési vagy elutasító határozatot küld vissza.
1. lépés: Hozzon létre egy központi eszköz-nyilvántartást
Az eszköznyilvántartás az a leltár, amely megakadályozza, hogy az „ismeretlen ügynök-képesség” legyen az alapértelmezett. Minden eszköznek rendelkeznie kell tulajdonossal, kockázati szinttel és működési metaadatokkal. Egy minimális nyilvántartási rekord így nézhet ki:
{
"tool_id": "crm.create_ticket",
"display_name": "CRM támogatási jegy létrehozása",
"owner_team": "támogatás-automatizálás",
"execution_type": "internal_api",
"server_url": "https://tools.internal.example/crm",
"allowed_tenants": ["vállalkozás", "támogatás"],"allowed_models": ["general-large", "general-fast"],
"risk_tier": "reversible_write",
"data_classification": "customer_metadata",
"required_scopes": ["tool:crm.create_ticket"],
"approval_policy": "not_required_under_100_tickets_per_day",
"default_timeout_ms": 8000,
"max_cost_per_call_usd": 0,05,
"max_calls_per_run": 3,
"rollback_owner": "support-ops-oncall",
"retention_policy": "redacted_30_days"
}MCP-kiszolgálók esetén a beállításjegyzéknek tartalmaznia kell a kiszolgáló URL-címét, a hirdetett eszközöket, a séma verzióját, az engedélyezési módot, az utolsó ellenőrzés dátumát és azt, hogy az új eszközök alapértelmezés szerint le vannak-e tiltva. Az MCP javítja az interoperabilitást, de a protokoll-kompatibilitás nem ugyanaz, mint a gyártási engedélyezés. Az érzékeny erőforrásokhoz és műveletekhez továbbra is explicit hatókörre, útvonal-ellenőrzésre és bérlői elkülönítésre van szükség.
Ajánlott regisztrációs mezők
- Az eszköz neve, kanonikus azonosítója, tulajdonosa és ügyeleti kapcsolattartója.
- Végrehajtás helye: tárolt szolgáltatói eszköz, MCP-kiszolgáló, belső API, böngésző-munkavégző, kódfutó, sorfeladat vagy helyi SDK-eszköz.
- Engedélyezett bérlők, csapatok, felhasználók, ügynökverziók és modellprofilok.
- Adatok besorolása: nyilvános, belső, ügyfél-metaadatok, ügyféltartalom, titkok, fizetési adatok, hitelesítő adatok, szabályozott adatok.
- Kockázati szint és visszafordíthatóság.
- Szükséges hatókör és jóváhagyási szabályzat.
- Időtúllépések, díjkorlátok, futásonkénti hívások maximális száma, kumulált futási költségkeret és maximális hívásonkénti költség.
- Naplózási mód: a teljes hasznos adattartalom tiltott, szerkesztett, kivonatolt, mintavételezés vagy kifejezetten megőrzött.
- Visszaállítási utasítások és eszkalációs útvonal.
2. lépés: A modell hatóköreinek elkülönítése az eszközhatókörtől
A termelési átjáró kulcsának azt kell kifejeznie, hogy a hívó mire képes. A modellelérésnek és a szerszám-hozzáférésnek függetlennek kell lennie. Például:
model:chat
modell: beágyazások
tool:docs.search_readonly
tool:crm.create_ticket
tool:email.send_requires_approval
tool:billing.refund_blocked
tool:code.execute_blockedEz megakadályozza, hogy egy alacsony kockázatú chatbot véletlenül automatizálási ügynökké váljon. Támogatja a szerepsablonokat is:
- Fejlesztői asszisztens: modellcsevegés, dokumentációkeresés, kódmagyarázat, éles írási eszközök nélkül.
- Támogató robot: ügyfélkeresés, jegy létrehozása, válasz megfogalmazása, jóváhagyás szükséges a külső küldéshez.
- Elemző ügynök: csak olvasható adattárház-lekérdezések sorkorlátozással, alapértelmezés szerint nincs ügyfélexportálás.
- Adminisztrációs ügynök: szűk kiváltságos műveletek, erős jóváhagyás, rövid élettartamú kulcsok, teljes ellenőrzés.
- Viszonteladó bérlői ügynök: bérlői hatókörű modellelérés, bérlői hatókörű eszközök, ügyfélenkénti költségkeret felső határa.
A javaslat a sikertelen bezárás: az ismeretlen eszközök le vannak tiltva, a hiányzó hatókörök megtagadják a végrehajtást, az újonnan hirdetett MCP-eszközök a jóváhagyásig inaktívak, és a helyi eszközöknek ugyanazt a házirend-burkolót kell használniuk, mint a tárolt eszközöknek.
3. lépés: Osztályozza az eszközöket robbanási sugár szerint
Nem minden eszközhíváshoz szükséges emberi jóváhagyás. Az irányításnak arányosnak kell lennie a kockázattal. Hasznos osztályozási modell:
Ennek a besorolásnak láthatónak kell lennie a kódellenőrzés során és az adminisztrációs felületen. Az eszközleírások önmagukban nem elegendőek, mert az ügynökök a leírásokat utasításként kezelhetik. A házirend-motornak a beállításjegyzék metaadataira és hatóköreire kell támaszkodnia, nem csak a természetes nyelvű eszköznevekre.
4. lépés: Adjon hozzá jóváhagyási kaput a magas kockázatú tevékenységekhez
A jóváhagyást célozni kell. Ha minden eszközhíváshoz személyre van szükség, az ügynök használhatatlanná válik. Ha egyetlen eszközhívás sem igényel jóváhagyást, a rendszer túlzott mértékű megbízást adhat.
Gyakori jóváhagyási folyamat:
- Az ügynök eszközhívást kér strukturált argumentumokkal.
- Az átjáró értékeli a személyazonosságot, a hatókört, a kockázati szintet, a költségvetést és a szabályzatot.
- Ha jóváhagyásra van szükség, az átjáró egy függőben lévő jóváhagyási eseményt ad vissza az eszköz végrehajtása helyett.
- Az alkalmazás előnézetet jelenít meg a felhasználó számára, vagy műveleti értesítést küld egy jóváhagyási csatornának.
- A jóváhagyó jóváhagyhatja, megtagadhatja, szerkesztheti az érveket, ha az irányelv megengedi, vagy pontosítást kérhet.
- Az átjáró rögzíti a döntést, és csak a jóváhagyott verziót hajtja végre.
A jóváhagyási terhelésnek emberi szemszögből kell megjelenítenie a műveletet, nem csak a nyers JSON-t:
{
"approval_id": "appr_123",
"agent_run_id": "run_456",
"requested_by_user": "user_789",
"tool_id": "email.send",
"risk_tier": "external_communication",
"summary": "Válasz küldése a [email protected] címre a 4812-es jegyről",
"redacted_arguments": {
"to": "[email protected]",
"subject": "Frissítés a 4812-es jegyhez",
"body_hash": "sha256:..."
},
"expires_at": "2026-08-09T12:30:00Z"
}A jóváhagyás leginkább a külső kommunikáció, a pénzügyi műveletek, a visszafordíthatatlan írások, a kiemelt adminisztráció és az adatok széles körű exportálása esetén hasznos. Általában szükségtelen kis mennyiségű nyilvános dokumentáció kereséséhez.
5. lépés: Kövesse nyomon az eszközenkénti költségkereteket és a díjkorlátokat
A token költségkeretek nem elegendőek. Egy olcsó modell költséges kereséseket, böngészőmunkameneteket, kódfuttatásokat, harmadik féltől származó API-hívásokat vagy hosszú szerszámhurkokat indíthat el. Az átjárónak legalább négy számlálót kell követnie:
- Eszközenkénti hívások száma: maximális hívások futtatásonként, felhasználónként, bérlőnként és időintervallumonként.
- Eszközönkénti költség: a harmadik fél közvetlen díjai, a böngésző/futási idő költsége, a keresési költség vagy a belső visszaterhelési becslés.
- Ügynök-futás kumulatív költsége: a modell tokenek plusz az eszközköltségek.
- Hurokmélység: a modell-eszköz-modell iterációk maximális száma.
Ha elér egy határt, az átjárónak lehetőség szerint kerülnie kell a csendes, kemény meghibásodást. A biztonságosabb leromlási minták közé tartozik az előrehaladás összegzésének visszaküldése, a folytatás jóváhagyásának kérése, a visszakeresési mélység csökkentése, a háttérfeladat sorba állítása vagy a csak olvasható módba váltás. A szigorú megtagadás továbbra is megfelelő blokkolt eszközök, hiányzó hatókörök, ismeretlen MCP-képességek és veszélyes műveletek esetén.
6. lépés: Csatlakoztassa a modell és a szerszám telemetriáját egyetlen audit rekordba
Az ügynökhibakeresés meghiúsul, ha a modellnaplók egy helyen, az eszköznaplók pedig máshol találhatók. Az ellenőrzési rekordnak össze kell kapcsolnia a teljes láncot:
- Bérlő, munkaterület, felhasználó, szolgáltatásfiók és átjárókulcs.
- Az ügynök azonosítója, az ügynök verziója, a prompt sablon verziója és a modellazonosító.
- Eszköz neve, rendszerleíró adatbázis verziója, kiszolgáló URL-je vagy végrehajtási környezete és séma hash.
- Eszközbeviteli hash vagy redukált bemenet, alapértelmezés szerint soha nem nyers érzékeny hasznos adatokat.
- Jóváhagyási állapot, jóváhagyó azonosítója, jóváhagyási időbélyegző és jóváhagyott argumentumkivonat.
- Késés, újrapróbálkozások, szolgáltatói hibák, szerszámhibák, token költség, eszközköltség és végeredmény.
- Visszaállítási hivatkozás, ha a művelet állapota megváltozott.
Az OpenAI's Agents SDK nyomkövetési dokumentációja tartalmazza az LLM-generációk nyomkövetését, az eszközhívásokat, az átadásokat, a védőkorlátokat és az egyéni eseményeket, ami egy tágabb megfigyelhetőségi elvet támogat: az ügynöknyomoknak tartalmazniuk kell az eszköztevékenységet, nem csak a tokenhasználatot és a késleltetést. Előfordulhat azonban, hogy egyetlen SDK-folyamat nem fed le minden tárolt eszközt, helyi végrehajtási útvonalat vagy belső API-t. Az átjárószintű audit segít normalizálni a rekordokat a szolgáltatók és keretrendszerek között.
Az adatvédelem számít. A részletes naplók javítják a hibakeresést és a megfelelőségi ellenőrzést, de a nyers prompt és az eszköz hasznos terhelésének megtartása új biztonsági kötelezettséget hozhat létre. A titkokat, hitelesítő adatokat, fizetési adatokat, személyes adatokat vagy védett dokumentumokat tartalmazó bemenetek szerkesztése vagy kivonatolása. A nyers hasznos terheket csak kifejezett megőrzési szabályzat, hozzáférés-szabályozás és törlési szabályok szerint tárolja.
7. lépés: Kezelje az MCP-kiszolgálókat és a harmadik féltől származó eszközöket ellátási lánc függőségeként
Az MCP-kiszolgálóknak és a harmadik féltől származó eszközöknek ugyanazon az ellenőrzési folyamaton kell keresztülmenniük, mint a könyvtáraknak, a webhooknak és az infrastruktúra-függőségeknek. A javasolt vezérlők a következők:
- Engedélyezőlistát tartson fenn a jóváhagyott MCP-kiszolgálókról és az eszközök eredeteiről.
- Ahol lehetséges, rögzítse a verziókat, és rögzítse a sémakivonatokat.
- Minden szerverhez és nagy kockázatú eszközhöz tulajdonost kell kérni.
- Tekintse át az eszközök nevét, leírását, sémáját és engedélykérelmét, mielőtt engedélyezné őket.
- Az újonnan hozzáadott eszközök letiltása az ellenőrzésig.
- Ellenőrizze a szükséges hatóköröket útvonalonként vagy képességenként.
- Válassza el a bérlői hitelesítési adatokat, és kerülje az ügyfelek közötti megosztott tokeneket.
- Futtasson nem megbízható vagy magas kockázatú eszközöket homokozókban, hálózati és fájlrendszer-korlátozásokkal.
Az a tény, hogy egy eszköz egy szabványos protokollon keresztül elérhető, még nem teszi biztonságossá. Az irányítási rétegnek továbbra is szüksége van a legkevesebb jogosultságra, kifejezett jogosultságra, verziókezelésre és auditálhatóságra.
Megvalósítási ellenőrzőlista
Irányelv kialakítása
- Szerepkör-sablonok meghatározása a gyakori ügynök-felhasználók és szolgáltatásfiókok számára.
- Hozzon létre külön hatókört a modellhívásokhoz és az eszközhívásokhoz.
- Osztályozza az eszközöket adatérzékenység, visszafordíthatóság, külső hatás, pénzügyi hatás és jogosultsági szint szerint.
- Alapértelmezett tiltás beállítása ismeretlen eszközök és hiányzó hatókörök esetén.
- Jóváhagyási szabályokat csak a magas kockázatú tevékenységekhez határozzon meg.
Átjáró végrehajtása
- Kérje meg minden ügynöktől, hogy hívja meg az eszközöket az átjárón vagy egy aláírt házirend-csomagolón keresztül.
- Végrehajtás előtt ellenőrizze a bérlőt, felhasználót, kulcsot, ügynököt, modellt, eszközt, hatókört, költségkeretet és jóváhagyási állapotot.
- A maximális szerszámbehívási mélység és a kumulált futási költség érvényesítése.
- Rögzítse az eszköz regisztrációs verzióját és a séma hash-ét minden híváshoz.
- A sikertelen lezárás, ha a házirend-motor nem tud döntést hozni.
Ellenőrzés és műveletek
- A modellhívások és az eszközhívások összekapcsolása egyetlen nyomkövetési vagy ügynöki futásazonosítóval.
- Alapértelmezés szerint módosítsa vagy hash-érzékeny eszközbemeneteket.
- Tartsa a jóváhagyási bizonyítékot a végső végrehajtási nyilvántartással.
- Eszközönkénti költségek és díjkorlátok elemzése az adminisztrátorok előtt.
- Dokumentum-visszaállítási tulajdonosok az állapotot módosító eszközökhöz.
Várható kompromisszumok
Konzisztencia versus integrációs erőfeszítés. Az átjárószintű irányítás következetes végrehajtást biztosít a modellek, SDK-k és csapatok között. A költség az átvételből fakad: a fejlesztőknek az eszközök végrehajtását a jóváhagyott útvonalon kell irányítaniuk, ahelyett, hogy közvetlenül az alkalmazás kódjából hívnák meg az eszközöket.
A legkevesebb jogosultság a házirend bonyolultságához képest. A finomszemcsés hatókör csökkenti a robbanási sugarat, de sablonokra, elnevezési konvenciókra és rendszeres tisztításra van szükség. Sablonok nélkül a csapatok túlzottan engedélyezhetik a gyorsabb mozgást.
Jóváhagyás versus autonómia. Az emberi jóváhagyás csökkenti a visszafordíthatatlan tevékenységek kockázatát, de növeli a várakozási időt. Használjon jóváhagyásokat a magas kockázatú eszközökhöz, ne minden kereséshez vagy kereséshez.
A vizsgázhatóság és az adatok nyilvánosságra hozatala. A gazdag naplók segítenek az incidensekre való reagálásban és a hibakeresésben. A nyers rakomány naplózása titkokat és személyes adatokat fedhet fel. A szerkesztés, a kivonatolás, a konfigurálható megőrzés és a hozzáférés ellenőrzése nem kötelező részlet.
Kemény korlátok a feladat befejezésével szemben. Az eszközenkénti költségkorlátok megakadályozzák a kifutó ügynököket. Megszakíthatják a jogszerű, hosszan tartó munkát is. Adja meg a folytatási útvonalakat, például a jóváhagyástól a folytatásig, a háttérben várólistákat vagy az összesített részeredményeket.
Előrejelzések: merre tart ez a minta
Előrejelzés: az ügynökirányítás identitásközpontúbbá válik. A csapatok ritkábban teszik fel a kérdést, hogy „melyik modellt használta ez?” és gyakrabban „melyik hitelesített személy vagy szolgáltatás engedélyezte ezt az eszközműveletet?”
Előrejelzés: az eszköznyilvántartások ugyanolyan normálisak lesznek, mint a modellnyilvántartások. Ahogy az MCP-kiszolgálók, a belső API-k és a hosztolt eszközök szaporodnak, a termelési csapatoknak szükségük lesz egy leltárra az engedélyezett képességekről, tulajdonosokról, sémákról és kockázati szintekről.
Előrejelzés: a költségirányítás a token-alapú jelentésről a cselekvési szintű jelentésekre fog áttérni. Az ügynökfutás legdrágább része lehet a visszakeresés, a böngésző automatizálása, a kódvégrehajtás vagy a harmadik féltől származó API-k, nem pedig maga a modellhívás.
Intézhető következtetés
Kezdje egy szabállyal: a modellkulcs nem eszközkulcs. Aztán építs kifelé. Hozzon létre egy nyilvántartást a jóváhagyott eszközökről, rendeljen hozzá tulajdonosokat és kockázati szinteket, írjon elő explicit hatóköröket, adjon hozzá jóváhagyásokat csak akkor, ha a műveletnek jelentős kitörési sugara van, kényszerítse ki az eszközenkénti költségvetést, és egyesítse a modell- és eszközeseményeket egyetlen ellenőrzési nyomvonalba.
Nem az a cél, hogy az ügynököket tehetetlenné tegyük. A cél az, hogy hatalmukat olvashatóvá, hatókörűvé, lehetőség szerint visszafordíthatóvá és elszámoltathatóvá tegyék. Ez a gyakorlati alapja a csapat API-irányításának, mivel az ügynökök a kérdések megválaszolásától a cselekvések felé haladnak.