Zarządzanie narzędziem agenta za pośrednictwem bramy API AI: zakresy, zatwierdzenia, budżety i ścieżki audytu
Praktyczna architektura referencyjna do zarządzania narzędziami agentów za pośrednictwem bramy API AI: rejestry narzędzi, klucze o określonym zakresie, bramki zatwierdzające, budżety na narzędzia, listy dozwolonych MCP i połączone ścieżki audytu modelu/narzędzia.
Ryzyko agenta nie ogranicza się już do podpowiedzi modelu. Agent produkcyjny może przeszukiwać pliki wewnętrzne, wysyłać zapytania do rekordów klientów, wywoływać serwer MCP, wykonywać kod, otwierać przeglądarkę, wysyłać wiadomości e-mail, aktualizować CRM lub uruchamiać przepływ pracy związany z rozliczeniami. Pytanie dotyczące zarządzania brzmi: który użytkownik, klucz, model, agent i narzędzie mogło podjąć jakie działanie, przy jakim budżecie, ścieżce audytu i ścieżce wycofywania?
Jeśli każdy zespół obsługuje dostęp do narzędzi w ramach własnego kodu SDK, zasady zostają rozproszone po zmiennych środowiskowych, pulpitach nawigacyjnych dostawców, oprogramowaniu pośrednim aplikacji i nieudokumentowanych serwerach MCP. Bezpieczniejszym wzorcem jest traktowanie wykonania narzędzia agenta jako problemu na płaszczyźnie kontrolnej i egzekwowanie go za pośrednictwem bramy AI API lub standardowego opakowania wykonywania narzędzia, którego musi używać każdy agent.
W tym artykule oddzielono fakty, zalecenia i przewidywania. Fakty zaczerpnięto z aktualnych wytycznych publicznych: 10 najważniejszych aplikacji LLM firmy OWASP obejmuje zagrożenia, takie jak ujawnianie informacji wrażliwych, słabe punkty łańcucha dostaw i nadmierna agencja; Profil generatywnej sztucznej inteligencji NIST dla ram zarządzania ryzykiem AI kładzie nacisk na mapowanie, mierzenie i zarządzanie ryzykami generatywnymi AI; Wytyczne dla agentów OpenAI zalecają ocenę ryzyka narzędzia na podstawie dostępu do odczytu/zapisu, odwracalności, uprawnień i wpływu finansowego; a wytyczne dotyczące autoryzacji MCP wykorzystują koncepcje autoryzacji o określonym zakresie dla wrażliwych zasobów i operacji. Poniższe zalecenia to wzorce wdrażania, a nie wymagania uniwersalne.
Problem czytelnika: dostęp do modelu i dostęp do narzędzi są mylone
W wielu wczesnych aplikacjach LLM klucz API odpowiadał na jedno podstawowe pytanie: czy ta usługa może wywołać model? Agenci sprawiają, że jest to zbyt szorstkie. Klucz, który może wysyłać informacje o uzupełnieniach czatu, nie powinien automatycznie umożliwiać eksportowania danych klientów, uruchamiania poleceń powłoki, wysyłania postów do Slacka, modyfikowania zgłoszeń, przeglądania dowolnych witryn internetowych ani przesyłania zmian w płatnościach.
Warstwa zarządzania musi odpowiedzieć na bardziej szczegółowe pytania:
- Który najemca, obszar roboczy, użytkownik, konto usługi lub klient-sprzedawca zainicjował uruchomienie?
- Jaki model, szablon podpowiedzi, wersja agenta i schemat narzędzia zostały użyte?
- Czy żądane narzędzie było tylko do odczytu, odwracalne, nieodwracalne, przeznaczone na zewnątrz, finansowe czy uprzywilejowane?
- Czy osoba żądająca miała wymagany zakres?
- Czy zgoda była wymagana, została udzielona, odrzucona, wygasła lub została pominięta w ramach zasad dotyczących sytuacji awaryjnych?
- Ile kosztowało narzędzie, ile razy zostało wywołane i jaki skumulowany budżet pozostał?
- Jakie istnieją dowody na debugowanie, sprawdzanie zgodności i wycofywanie zmian?
W poniższej architekturze przyjęto, że brama odbiera już wywołania modelowe. Wykonanie narzędzia można następnie skierować przez tę samą bramę, przez usługę przyczepki lub przez standardową bibliotekę, która raportuje do bramy przed i po każdym wywołaniu narzędzia.
Architektura referencyjna: warstwa zarządzania narzędziami na poziomie bramy
Praktyczny system zarządzania agentami składa się z siedmiu elementów:
- Rejestr narzędzi: autorytatywna lista zatwierdzonych narzędzi, serwerów MCP, hostowanych funkcji, lokalnych narzędzi wykonawczych i wewnętrznych interfejsów API.
- Tożsamość i warstwa kluczowa: klucze bramy, użytkownicy, dzierżawcy, konta usług, zespoły i klienci-sprzedawcy.
- Silnik zakresu: sprawdza zasady, które decydują, czy klucz lub użytkownik może wywołać określoną funkcję narzędzia.
- Klasyfikator ryzyka: metadane opisujące promień wybuchu, wrażliwość danych, odwracalność, wpływ zewnętrzny i ekspozycję na koszty.
- Przebieg zatwierdzania: zatwierdzenie przez człowieka lub system działań obarczonych wysokim ryzykiem przed ich wykonaniem.
- Księga budżetów i limitów stawek: limity na narzędzie i agenta, a nie tylko limity tokenów na model.
- Audyt i przechowywanie śladów: połączone rekordy dla wywołań modeli, wywołań narzędzi, zatwierdzeń, błędów i wyników.
Ważną decyzją projektową jest uczynienie bramy punktem podejmowania decyzji politycznych, nawet jeśli faktyczne narzędzie działa gdzie indziej. Na przykład narzędzie przeglądarki może zostać wykonane w procesie roboczym w trybie piaskownicy, a zapis CRM może zostać wykonany w ramach usługi wewnętrznej. Bramka nadal ocenia, czy połączenie jest dozwolone, rejestruje decyzję, śledzi koszty i zwraca podpisaną decyzję autoryzacyjną lub odmowę.
Krok 1: Zbuduj centralny rejestr narzędzi
Rejestr narzędzi to spis, który zapobiega sytuacji, w której „możliwość nieznanego agenta” staje się domyślną. Każde narzędzie powinno mieć właściciela, poziom ryzyka i metadane operacyjne. Minimalny zapis rejestru może wyglądać następująco:
{ "tool_id": "crm.create_ticket", "display_name": "Utwórz zgłoszenie do pomocy technicznej CRM", "owner_team": "automatyzacja wsparcia", "type_execution_type": "wewnętrzny_api", "server_url": "https://tools.internal.example/crm", „allowed_tenants”: [„przedsiębiorstwo”, „wsparcie”],„allowed_models”: [„general-large”, „general-fast”], "risk_tier": "reversible_write", "data_classification": "metadane_klienta", „required_scopes”: [„narzędzie: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": "wsparcie operacyjne na wezwanie", "retention_policy": "redacted_30_days"
W przypadku serwerów MCP rejestr powinien również zawierać adres URL serwera, reklamowane narzędzia, wersję schematu, metodę autoryzacji, datę ostatniego przeglądu oraz informację, czy nowe narzędzia są domyślnie wyłączone. MCP poprawia interoperacyjność, ale zgodność protokołów to nie to samo, co autoryzacja produkcji. Wrażliwe zasoby i operacje nadal wymagają jawnych zakresów, kontroli tras i izolacji dzierżawców.
Zalecane pola rejestru
- Nazwa narzędzia, identyfikator kanoniczny, właściciel i kontakt telefoniczny.
- Lokalizacja wykonania: narzędzie dostawcy hostowanego, serwer MCP, wewnętrzny interfejs API, proces roboczy przeglądarki, moduł uruchamiający kod, zadanie kolejki lub lokalne narzędzie SDK.
- Dozwoleni najemcy, zespoły, użytkownicy, wersje agentów i profile modeli.
- Klasyfikacja danych: publiczne, wewnętrzne, metadane klienta, treść klienta, tajemnice, dane dotyczące płatności, dane uwierzytelniające, dane regulowane.
- Poziom ryzyka i odwracalność.
- Wymagane zakresy i zasady zatwierdzania.
- Przekroczenia limitów czasu, limity szybkości, maksymalna liczba połączeń na uruchomienie, skumulowany budżet na uruchomienie i maksymalny koszt połączenia.
- Tryb rejestrowania: zabroniony pełny ładunek, zredagowany, zaszyfrowany, próbkowany lub jawnie zachowany.
- Instrukcje wycofywania zmian i ścieżka eskalacji.
Krok 2: oddziel zakresy modelu od zakresów narzędzi
Klucz bramy produkcyjnej powinien określać, co może zrobić osoba wywołująca. Dostęp do modelu i dostęp do narzędzi powinny być niezależne. Na przykład:
model:czat
model: osadzenia
narzędzie:docs.search_readonly
narzędzie:crm.create_ticket
narzędzie:email.send_requires_approval
narzędzie:billing.refund_blocked
narzędzie:code.execute_blockedDzięki temu chatbot niskiego ryzyka nie stanie się przypadkowym agentem automatyzacji. Obsługuje także szablony ról:
- Asystent programisty: czat modelowy, wyszukiwanie dokumentacji, objaśnianie kodu, brak narzędzi do pisania produkcyjnego.
- Bot wsparcia: wyszukiwanie klientów, tworzenie zgłoszeń, redagowanie odpowiedzi, wymagane zatwierdzenie wysyłek zewnętrznych.
- Agent analityk: zapytania dotyczące hurtowni danych tylko do odczytu z limitami wierszy, domyślnie bez eksportu klientów.
- Agent administracyjny: wąskie operacje uprzywilejowane, silne zatwierdzenie, klucze krótkotrwałe, pełny audyt.
- Agent-dzierżawca-sprzedawca: dostęp do modelu w zakresie najemcy, narzędzia dostosowane do najemcy, pułapy budżetu na klienta.
Zalecane jest zamknięcie porażką: odmowa nieznanych narzędzi, brakujące zakresy odmowa wykonania, nowo reklamowane narzędzia MCP są nieaktywne do czasu zatwierdzenia, a narzędzia lokalne muszą używać tego samego opakowania zasad co narzędzia hostowane.
Krok 3: Klasyfikuj narzędzia według promienia wybuchu
Nie każde wywołanie narzędzia wymaga zgody człowieka. Zarządzanie powinno być proporcjonalne do ryzyka. Przydatnym modelem klasyfikacji jest:
Ta klasyfikacja powinna być widoczna podczas przeglądu kodu i w interfejsie administratora. Same opisy narzędzi nie wystarczą, ponieważ agenci mogą traktować opisy jako instrukcje. Silnik zasad powinien opierać się na metadanych i zakresach rejestru, a nie tylko na nazwach narzędzi w języku naturalnym.
Krok 4: Dodaj bramki zatwierdzające dla działań wysokiego ryzyka
Zatwierdzenie powinno być ukierunkowane. Jeśli każde wywołanie narzędzia wymaga obecności osoby, agent stanie się bezużyteczny. Jeśli żadne wywołanie narzędzia nie wymaga zatwierdzenia, system może przyznać nadmierną swobodę działania.
Wspólny proces zatwierdzania:
- Agent żąda wywołania narzędzia z argumentami strukturalnymi.
- Brama ocenia tożsamość, zakres, poziom ryzyka, budżet i zasady.
- Jeśli wymagane jest zatwierdzenie, brama zamiast wykonać narzędzie, zwraca zdarzenie oczekujące na zatwierdzenie.
- Aplikacja wyświetla podgląd użytkownikowi lub wysyła powiadomienie operacyjne do kanału zatwierdzającego.
- Osoba zatwierdzająca może zatwierdzić, odrzucić, edytować argumenty, jeśli pozwalają na to zasady, lub poprosić o wyjaśnienia.
- Brama rejestruje decyzję i wykonuje tylko zatwierdzoną wersję.
Ładunek zatwierdzający powinien przedstawiać działanie w kategoriach ludzkich, a nie tylko surowego JSON:
{ "approval_id": "appr_123", "agent_run_id": "run_456", "requested_by_user": "user_789", "tool_id": "e-mail.wyślij", "risk_tier": "komunikacja zewnętrzna", "summary": "Wyślij odpowiedź na adres [email protected] w sprawie zgłoszenia nr 4812", „redacted_arguments”: { "do": "[email protected]", "temat": "Aktualizacja zgłoszenia nr 4812", "body_hash": "sha256:..." }, "expires_at": "2026-08-09T12:30:00Z"
Zatwierdzanie jest najbardziej przydatne w przypadku komunikacji zewnętrznej, działań finansowych, nieodwracalnych zapisów, uprzywilejowanej administracji i szerokiego eksportu danych. Zwykle nie jest to konieczne w przypadku przeszukiwania dokumentacji publicznej o małej objętości.
Krok 5: Śledź budżety poszczególnych narzędzi i limity stawek
Budżety tokenowe nie są wystarczające. Tani model może powodować kosztowne wyszukiwania, sesje przeglądarki, uruchamianie kodu, wywołania API stron trzecich lub długie pętle narzędzi. Brama powinna śledzić co najmniej cztery liczniki:
- Liczba wywołań na narzędzie: maksymalna liczba wywołań na uruchomienie, użytkownika, dzierżawcę i przedział czasowy.
- Koszt narzędzia: bezpośrednie opłaty na rzecz osób trzecich, koszt przeglądarki/czasu działania, koszt wyszukiwania lub szacunkowy koszt wewnętrznego obciążenia zwrotnego.
- Skumulowany koszt działania agenta: tokeny modeli plus koszty narzędzi.
- Głębokość pętli: maksymalna liczba iteracji model-narzędzie-model.
Po osiągnięciu limitu brama powinna, jeśli to możliwe, unikać cichej, twardej awarii. Bezpieczniejsze wzorce degradacji obejmują zwracanie podsumowania postępu, proszenie o zgodę na kontynuację, zmniejszanie głębokości pobierania, kolejkowanie zadania w tle lub przełączanie do trybu tylko do odczytu. Twarda odmowa jest nadal odpowiednia w przypadku zablokowanych narzędzi, brakujących zakresów, nieznanych możliwości MCP i niebezpiecznych działań.
Krok 6: Połącz dane telemetryczne modelu i narzędzia w jeden rekord audytu
Debugowanie agenta kończy się niepowodzeniem, gdy dzienniki modelu znajdują się w jednym miejscu, a dzienniki narzędzi w innym miejscu. Rekord audytu powinien łączyć cały łańcuch:
- Najemca, obszar roboczy, użytkownik, konto usługi i klucz bramy.
- Identyfikator agenta, wersja agenta, wersja szablonu podpowiedzi i identyfikator modelu.
- Nazwa narzędzia, wersja rejestru, adres URL serwera lub środowisko wykonawcze oraz skrót schematu.
- Skrót danych wejściowych narzędzia lub zredagowane dane wejściowe, domyślnie nigdy nieprzetworzone wrażliwe ładunki.
- Stan zatwierdzenia, tożsamość osoby zatwierdzającej, sygnatura czasowa zatwierdzenia i skrót zatwierdzonego argumentu.
- Opóźnienia, ponowne próby, błędy dostawcy, błędy narzędzi, koszt tokena, koszt narzędzia i wynik końcowy.
- Odniesienie do wycofania, jeśli akcja zmieniła stan.
Dokumentacja śledzenia pakietu SDK agentów OpenAI obejmuje ślady generacji LLM, wywołania narzędzi, przekazania, poręcze i zdarzenia niestandardowe, co wspiera szerszą zasadę obserwowalności: ślady agentów powinny obejmować aktywność narzędzia, a nie tylko użycie tokenu i opóźnienie. Jednak pojedynczy potok SDK może nie obejmować każdego hostowanego narzędzia, lokalnej ścieżki wykonania lub wewnętrznego interfejsu API. Audyt na poziomie bramy pomaga normalizować zapisy między dostawcami i platformami.
Prywatność ma znaczenie. Szczegółowe dzienniki usprawniają debugowanie i kontrolę zgodności, ale zachowanie nieprzetworzonych podpowiedzi i ładunku narzędzi może stworzyć nowe zagrożenie dla bezpieczeństwa. Redaguj lub szyfruj dane wejściowe zawierające sekrety, dane uwierzytelniające, dane dotyczące płatności, dane osobowe lub dokumenty zastrzeżone. Przechowuj surowe ładunki wyłącznie zgodnie z wyraźnymi zasadami przechowywania, kontrolą dostępu i regułami usuwania.
Krok 7: traktuj serwery MCP i narzędzia innych firm jako zależności w łańcuchu dostaw
Serwery MCP i narzędzia innych firm powinny przejść ten sam proces sprawdzania, co biblioteki, webhooki i zależności infrastruktury. Zalecane elementy sterujące obejmują:
- Prowadź listę dozwolonych zatwierdzonych serwerów MCP i źródeł narzędzi.
- Przypinaj wersje, jeśli to możliwe, i zapisuj skróty schematów.
- Wymagaj właściciela dla każdego serwera i narzędzia wysokiego ryzyka.
- Przejrzyj nazwy narzędzi, opisy, schematy i uprawnienia przed ich włączeniem.
- Wyłącz nowo dodane narzędzia do czasu sprawdzenia.
- Sprawdź wymagane zakresy dla każdej trasy lub możliwości.
- Oddziel poświadczenia dzierżawy i unikaj udostępniania tokenów klientom.
- Uruchamiaj narzędzia niezaufane lub narzędzia wysokiego ryzyka w piaskownicach z ograniczeniami sieci i systemu plików.
Fakt, że narzędzie jest ujawniane za pomocą standardowego protokołu, nie oznacza, że jest ono bezpieczne. Warstwa zarządzania nadal wymaga najmniejszych uprawnień, wyraźnej autoryzacji, kontroli wersji i możliwości audytu.
Lista kontrolna wdrożenia
Projekt polityki
- Zdefiniuj szablony ról dla zwykłych użytkowników agentów i kont usług.
- Utwórz osobne zakresy dla wywołań modeli i wywołań narzędzi.
- Klasyfikuj narzędzia według wrażliwości danych, odwracalności, wpływu zewnętrznego, wpływu finansowego i poziomu uprawnień.
- Ustaw domyślne zachowanie odmowy dla nieznanych narzędzi i brakujących zakresów.
- Określ reguły zatwierdzania tylko dla działań o wysokim ryzyku.
Egzekwowanie bramy
- Wymagaj, aby każdy agent wywoływał narzędzia przez bramę lub podpisane opakowanie zasad.
- Przed wykonaniem sprawdź najemcę, użytkownika, klucz, agenta, model, narzędzie, zakres, budżet i stan zatwierdzenia.
- Egzekwuj maksymalną głębokość wywołań narzędzi i skumulowany koszt eksploatacji.
- Rejestruj wersję rejestru narzędzia i skrót schematu dla każdego wywołania.
- Awaria zamknięta, gdy aparat zasad nie może podjąć decyzji.
Audyt i operacje
- Łącz wywołania modeli i wywołania narzędzi w ramach jednego identyfikatora śledzenia lub uruchomienia agenta.
- Domyślnie redaguj lub mieszaj dane wejściowe narzędzia.
- Zachowaj dowód zatwierdzenia wraz z końcowym protokołem wykonania.
- Udostępnij administratorom analizę kosztów poszczególnych narzędzi i limitów szybkości.
- Właściciele wycofywania dokumentów w przypadku narzędzi zmieniających stan.
Kompromisów, których można się spodziewać
Spójność a wysiłek związany z integracją. Zarządzanie na poziomie bramy zapewnia spójne egzekwowanie we wszystkich modelach, pakietach SDK i zespołach. Kosztem jest przyjęcie: programiści muszą kierować wykonywanie narzędzi zatwierdzoną ścieżką, zamiast wywoływać narzędzia bezpośrednio z kodu aplikacji.
Najmniejsze uprawnienia w porównaniu ze złożonością zasad. Precyzyjne zakresy zmniejszają promień wybuchu, ale wymagają szablonów, konwencji nazewnictwa i regularnego czyszczenia. Bez szablonów zespoły mogą przyznawać nadmierne uprawnienia, aby przyspieszyć działanie.
Aprobata a autonomia. Zatwierdzenie przez człowieka zmniejsza ryzyko nieodwracalnych działań, ale zwiększa opóźnienie. Używaj zatwierdzeń narzędzi wysokiego ryzyka, a nie każdego wyszukiwania lub wyszukiwania.
Możliwość kontroli a udostępnianie danych. Bogate dzienniki pomagają w reagowaniu na incydenty i debugowaniu. Rejestrowanie nieprzetworzonych ładunków może ujawnić sekrety i dane osobowe. Redakcja, haszowanie, konfigurowalne przechowywanie i kontrola dostępu nie są szczegółami opcjonalnymi.
Twarde limity a wykonanie zadania. Limity kosztów poszczególnych narzędzi zapobiegają uciekającym agentom. Mogą również przerwać legalną, długotrwałą pracę. Podaj ścieżki kontynuacji, takie jak zatwierdzenie kontynuacji, kolejki w tle lub podsumowane wyniki częściowe.
Prognozy: dokąd zmierza ten wzór
Przewidywanie: zarządzanie agentami stanie się bardziej skoncentrowane na tożsamości. Zespoły rzadziej będą pytać „z jakiego modelu korzystał ten model?” i częściej „która uwierzytelniona osoba lub usługa zezwoliła na działanie tego narzędzia?”
Przewidywanie: rejestry narzędzi staną się tak samo normalne, jak rejestry modeli. W miarę mnożenia się serwerów MCP, wewnętrznych interfejsów API i hostowanych narzędzi zespoły produkcyjne będą potrzebować spisu dozwolonych możliwości, właścicieli, schematów i poziomów ryzyka.
Przewidywanie: zarządzanie kosztami przejdzie z raportowania opartego wyłącznie na tokenach do raportowania na poziomie działania. Najdroższą częścią działania agenta może być pobieranie, automatyzacja przeglądarki, wykonanie kodu lub interfejsy API innych firm, a nie samo wywołanie modelu.
Wniosek, który można zastosować
Zacznij od jednej reguły: klucz modelu nie jest kluczem narzędzia. Następnie buduj na zewnątrz. Utwórz rejestr zatwierdzonych narzędzi, przypisz właścicieli i poziomy ryzyka, wymagaj wyraźnych zakresów, dodawaj zatwierdzenia tylko tam, gdzie działanie ma znaczący zasięg, egzekwuj budżety na poszczególne narzędzia oraz łącz zdarzenia dotyczące modelu i narzędzia w jedną ścieżkę audytu.
Celem nie jest uczynienie agentów bezsilnymi. Celem jest uczynienie ich władzy czytelną, zakresową, odwracalną, tam gdzie to możliwe, i odpowiedzialną. Stanowi to praktyczną podstawę zarządzania interfejsem API zespołu, gdy agenci przechodzą od odpowiadania na pytania do podejmowania działań.