Strona główna / Artykuły / Po kursie LangGraph: Twarde krawędzie, schematy i warstwy bezpieczeństwa

langgraph safety structured-output agents sql production

Po kursie LangGraph: Twarde krawędzie, schematy i warstwy bezpieczeństwa

Przekształć działającego agenta SQL w bezpieczniejszy za pomocą zabezpieczeń typowych, odświeżania schematu, planowania kosztów oraz wielopoziomowej weryfikacji.

2742 słów

Po kursie – zielona pieczątka

Kursy LangGraph pokazują, jak uruchomić graf. Ocena rozpoczyna się wtedy, gdy ktoś pyta, dlaczego każda decyzja jest bezpieczna. Ta wersja opisuje tydzień pracy nad przekształceniem agenta w stylu analityka SQL w coś odpornego na krytykę: architektury, które nie mogą ignorować zasad bezpieczeństwa, ustrukturyzowane wyniki, aktualność schematów, świadomość kosztów oraz błędy wykrywane podczas ich dokumentowania.

Sytuacja i zadanie

Kursy dostarczają ścieżki kodów prezentacyjnych, a nie invariantów. Zadaniem było utrzymanie działającego projektu przy jednoczesnym zapewnieniu, że każda gałąź będzie możliwa do zrozumienia podczas audytu – szczególnie te, które wykorzystują SQL.

Działanie 1 – dwie architektury, dzięki którym żadna nie może ominąć mechanizmu bezpieczeństwa

Brama bezpieczeństwa musi stanowić sztywną zasadę, a nie sugestię pochodzącą z promptu. Ustrukturyzowane oceny powinny znajdować się w skategoryzowanych schematach:

class JudgeAgentSchema(BaseModel):
    answer: Literal["yes", "no"] = Field(
        description="Return 'yes' if the SQL query ONLY retrieves data (like SELECT). "
                    "Return 'no' if it modifies data (like INSERT, UPDATE, DELETE, DROP)."
    )
    comments: str = Field(default="", description="Reasoning behind the verdict")


llm_judge = llm.with_structured_output(schema=JudgeAgentSchema)

Ścieżka z wyraźną warunkiem:

def is_safe_sql_condition(state: AgentSchema) -> str:
    if state.is_safe.lower() == "yes":
        return "Execute_SQL"
    return "Cancel_SQL_if_Not_Safe"

Błędy walidacji pojawiają się, gdy model odbiega od literalnego słownika:

ValidationError: Input should be 'yes' or 'no'
[type=literal_error, input_value='No', input_type=str]

@field_validator('answer', mode='before')
@classmethod
def normalize_answer(cls, v):
    if isinstance(v, str):
        v = v.strip().lower()
    return v if v in ("yes", "no") else "no"   # fail closed

ValidationError: Input should be 'yes' or 'no'
[type=literal_error, input_value='', input_type=str]

Ustalaj enumy i domyślne wartości ostrożnie:

is_safe: Literal["yes", "no"] = Field(default="no")      # fail closed
generated_sql_query: str = Field(default="")
messages: Annotated[list, add] = Field(default_factory=list)  # not default=[]

PydanticJsonSchemaWarning: Default value (...) is not JSON serializable

comments: str = (
    Field(..., description="..."),   # ← trailing comma makes this a tuple
)

def prompt_query_context(state: AgentSchema) -> AgentSchema:
    database_object = Database(connection_details)
    schema_info = database_object.get_schema_details("public")

Działanie 2 — strukturyzowany wynik jako komponent programowalny

Gdy odpowiedzi bezpieczeństwa stają się literalne, krawędzie przekształcają się w kod. Model jest komponentem z umową, a nie opisującym przepływ sterowania.

Działanie 3 — ponowne pobieranie schematu przy każdym uruchomieniu

Stare schema w zapytaniach powoduje błędne SQL. Odświeżanie kosztuje tokeny; stare dane powodują incydenty. Preferuj pobieranie schematu przy każdym uruchomieniu w przypadku zmieniających się baz danych, chyba że wersja jest wyraźnie określona.

Działanie 4 — koszt agenta ≠ koszt pipeline’a

Agenci działają w pętlach. Planuj budżet z uwzględnieniem ograniczeń rekurencji oraz tańszych modeli do kierowania ruchem:

def pick_llm(model_level: str) -> ChatAnthropic:
    if normalized_level == "basic":
        return ChatAnthropic(model="claude-haiku-4-5", temperature=0)
    elif normalized_level == "advanced":
        return ChatAnthropic(model="claude-sonnet-4-6", temperature=0)
    elif normalized_level == "premium":
        return ChatAnthropic(model="claude-opus-4-6", temperature=0)

Odsłonięte błędy w kodzie

Zmniejszacz i węzeł oba dodają dane

messages: Annotated[list, add] = Field(default_factory=list)

state.messages = state.messages + [response]   # full list: old + new
return state                                    # reducer adds it AGAIN

def sql_node(state: DataAgentSchema):
    response = sql_analyst.invoke({...})
    return {"messages": [AIMessage(content=response["final_answer"])]}

Wybierz jednego autora: reduktora lub węzeł, nie obu.

Przekazywanie całego stanu podagenta w górę

response = sql_analyst.invoke({...})   # returns the full AgentSchema dict
state.messages = state.messages + [response]

Przesyłaj tylko te pola, których potrzebuje rodzic.

Jednowarstwowa bezpieczeństwo probabilistyczne

Udostępnienie danych do bazy i analiza zapytań SQL muszą wspierać decyzje modelu:

POSTGRES_USER: agent_user
POSTGRES_PASSWORD: agent_pass

import sqlparse

def is_read_only(sql: str) -> bool:
    statements = sqlparse.parse(sql)
    if len(statements) != 1:          # blocks stacked queries
        return False
    return statements[0].get_type() == "SELECT"

CREATE ROLE agent_readonly LOGIN PASSWORD '...';
GRANT CONNECT ON DATABASE agent_db TO agent_readonly;
GRANT USAGE ON SCHEMA public TO agent_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO agent_readonly;

Obrona wielowarstwowa: brama modelu + parser + użytkownik bazy o minimalnych uprawnieniach.

Wynik i ograniczenia

Graf stał się poddawalny ocenie: krawędzie zapewniają bezpieczeństwo, schematy są zamknięte, koszty są celowe, a warstwy się nakładają. Ograniczeniem są ciągłe oceny i testy chaotyczne – nie kolejny rozdział w podręczniku.

Zasady, których należy przestrzegać

Napisz ADR-y dla odgałęzień architektury. Przetestuj niewłaściwe ścieżki. Zapisuj wersje schematu. Oddziel uprawnienia IAM narzędzi. Przeczytaj ponownie funkcje redukcyjne po każdej zmianie stanu. Tutorials kończą się na uruchomieniu kodu; produkcja zaczyna się od podjętych, dobrze przemyślanych decyzji.

Doskonała intuicja liczbowa

Załóżmy, że realizacja danego kroku kosztuje 10 ms, a projekt proponuje 5 tokenów o średnim wskaźniku akceptacji 60% dla 3 tokenów. Efektywny koszt za przyjęty token jest niższy w porównaniu z krokami opartymi na jednym tokenie, nawet po uwzględnieniu dodatkowych kosztów projektu, o ile wskaźnik akceptacji pozostaje wysoki. Jeśli wskaźnik akceptacji spadnie do około 1 tokena, schemat przegrywa. To właśnie ta wrażliwość sprawia, że tablice kontrolne są lepsze od anegdot.

Protokół regresji jakości

Zanim włączysz to na poziomie globalnym, przetestuj ustalone prompty we wszystkich zestawach zadań dotyczących faktów, programowania oraz sytuacji odrzucenia. Porównaj wskaźniki identyczności tokenów, gdy konfigurowane jest podejście spekulatywne w celu uzyskania dokładnego dopasowania rozkładu. Zbadaj ewentualne systematyczne odchylenia. Aby szybko ocenić efekty, śledź wskaźnik sukcesów w zadaniach ocenianych oraz preferencje ludzkie, jeśli są dostępne.

Rozmieszczenie sprzętu

Gdy to możliwe, umieść wersję roboczą i wersję końcową na tym samym węźle. Przenoszenie wersji roboczych między serwerami powoduje fluktuacje sieciowe, które mogą zniwelować osiągnięte korzyści. Uważaj na pamięć: dwa modele wraz z buforem KV mogą wyczerpać zasoby systemu, który wcześniej bez problemów obsługiwał tylko jeden model.

Planowanie interakcji

Serwery obsługujące ciągłe grupowanie zadań muszą uwzględniać zmienne rozmiary grup powstałych w wyniku podejścia spekulatywnego. Niewłaściwe planery powodują fragmentację grup zadań, co negatywnie wpływa na wykorzystanie zasobów. Koordynuj działania z administratorami serwerów; nie zmieniaj ustawień tylko w kodzie aplikacji.

Ciągła transparentność w identyfikacji wąskich gardeł

Po poprawie dekodowania użytkownicy mogą nadal czekać na wywołania narzędzi, pobieranie danych lub przetwarzanie Markdown po stronie klienta. Należy śledzić proces od początku do końca. Optymalizacja w niewłaściwych obszarach marnuje czas inżynierów.

Podsumowanie

Sekwencyjne dekodowanie stanowi strukturalny koszt związany z autoregresją. Dekodowanie spekulatywne oraz wczesne zakończenie procesu zmniejszają ten koszt w mierzalnych warunkach. Należy je wdrożyć z taką samą dyscypliną jak każdą funkcję produkcyjną: metryki, flagi, możliwość cofnięcia zmian oraz jasno określeni odpowiedzialni w zespole platformy serwisowej.

Liczbowe intuicje

Załóżmy, że jeden krok dekodowania kosztuje 10 ms, a wersja robocza proponuje 5 tokenów o średnim wskaźniku akceptacji 60% dla 3 tokenów. Efektywny koszt na akceptowany token jest niższy w porównaniu z klasycznymi krokami jednotonowymi, nawet po uwzględnieniu dodatkowych kosztów wersji roboczej, o ile wskaźnik akceptacji pozostaje wysoki. Jeśli wskaźnik spadnie do około 1 tokena, taki schemat staje się nierentowny. To właśnie ta wrażliwość sprawia, że tablice kontrolne są lepsze od anegdot.

Protokół regresji jakości

Zanim włączysz go globalnie, przetestuj ustalone prompty w zestawach dotyczących faktografii, programowania oraz sytuacji odrzucenia. Porównaj wskaźniki identyczności tokenów, gdy konfiguracja spekulatywna ma zapewnić dokładne dopasowanie rozkładu. Zbadaj wszelkie systematyczne odchylenia. Aby wcześniej zakończyć testy, śledź wskaźnik sukcesów w zadaniach ocenianych oraz preferencje ludzkie, jeśli są dostępne.

Rozmieszczenie sprzętu

Gdzie to możliwe, umieść wersję roboczą i docelową na tym samym węźle. Przenoszenie wersji roboczych między serwerami powoduje fluktuacje sieciowe, które mogą zniwelować osiągnięte korzyści. Uważaj na pamięć: dwa modele wraz z buforem KV mogą wyczerpać zasoby systemu, który wcześniej bez problemów obsługiwał jeden model.

Planowanie interakcji

Serwery obsługujące ciągłe grupowanie zadań muszą uwzględniać zmienne rozmiary grup spekulatywnych. Niewłaściwe planery powodują fragmentację grup zadań, co negatywnie wpływa na wykorzystanie zasobów. Koordynuj działania z administratorami serwerów; nie zmieniaj ustawień tylko w kodzie aplikacji.

Prawdomówność dotycząca pozostałych wąskich gardeł

Podsumowanie

Liczbowe intuicje

Załóżmy, że jeden krok w procesie kosztuje 10 ms, a projekt proponuje 5 tokenów o średnim wskaźniku akceptacji 60% dla 3 tokenów. Efektywny koszt na akceptowany token jest niższy w porównaniu z klasycznymi krokami obejmującymi jeden token, nawet po uwzględnieniu dodatkowych kosztów związanych z projektem, o ile wskaźnik akceptacji pozostaje wysoki. Jeśli wskaźnik spadnie do około 1 tokena, taki schemat staje się nierentowny. To właśnie ta wrażliwość sprawia, że tablice kontrolne są lepsze od anegdot.

Protokół regresji jakości

Rozmieszczenie sprzętu

Planowanie interakcji

Serwery obsługujące ciągłe grupowanie zadań muszą uwzględniać zmienne rozmiary grup spekulatywnych. Niewłaściwe planery fragmentują grupy zadań, co pogarsza wykorzystanie zasobów. Koordynuj działania z administratorami serwerów; nie zmieniaj ustawień tylko w kodzie aplikacji.

Prawdomówność dotycząca pozostałych wąskich gardeł

Po poprawie dekodowania użytkownicy mogą nadal czekać na wywołania narzędzi, pobieranie danych lub przetwarzanie Markdown na stronie klienta. Należy śledzić proces od początku do końca. Optymalizacje w niewłaściwych miejscach marnują czas inżynierów.

Podsumowanie

Sekwencyjne dekodowanie stanowi strukturalny koszt związany z autoregresją. Dekodowanie spekulatywne oraz wczesne zakończenie procesu zmniejszają ten koszt w określonych warunkach. Należy je wdrożyć z taką samą dyscypliną jak każdą funkcję produkcyjną: metryki, flagi, możliwość cofnięcia zmian oraz jasno określeni odpowiedzialni w zespole platformy serwisowej.

Opis dla recenzentów

W PR należy wyjaśnić, dlaczego istnieją dwie architektury: jedna z nich pokazuje, że pominięcie określonej ochrony jest niemożliwe, ponieważ brakuje odpowiedniego warunku granicznego. Taki diagram jest tym, czego potrzebują audytorzy artefaktów. Należy go połączyć z testami, które zawodzą przy próbie wywołania węzła SQL bez poprawnego literala bezpieczeństwa.

Wyjaśnij panel sterowania kosztami obok paneli sterujących jakością, aby nie dało się ukryć zasady „po prostu użyj największego modelu”. Opisz odświeżanie schematu na przykładzie historii związanej ze zmianą nazwy kolumny. Historie docierają dalej niż same listy kontrolne, ale nie pomijaj ich również.

Doskonała intuicja liczbowa

Załóżmy, że realizacja danego kroku kosztuje 10 ms, a projekt proponuje 5 tokenów o średnim wskaźniku akceptacji 60% dla 3 tokenów. Efektywny koszt na akceptowany token jest niższy w porównaniu z krokami obejmującymi jeden token, nawet po uwzględnieniu dodatkowych kosztów projektowania, o ile wskaźnik akceptacji pozostaje wysoki. Jeśli wskaźnik spadnie do około 1 tokena, taki schemat przegrywa. To właśnie ta wrażliwość sprawia, że panele sterujące są lepsze od anegdot.

Protokół regresji jakości

Rozmieszczenie sprzętu

Gdzie to możliwe, umieść wersję roboczą i wersję końcową na tym samym węźle. Przenoszenie wersji roboczych między serwerami powoduje fluktuacje sieciowe, które mogą zniwelować osiągnięte korzyści. Uważaj na pamięć: dwa modele wraz z cache’em KV mogą wyczerpać zasoby systemu, który wcześniej bez problemów obsługiwał tylko jeden model.

Planowanie interakcji

Serwery obsługujące ciągłe grupowanie zadań muszą uwzględniać zmienne rozmiary grup powstałych w wyniku podejścia spekulatywnego. Niewłaściwe planery powodują fragmentację grup zadań, co negatywnie wpływa na wykorzystanie zasobów. Koordynuj działania z osobami odpowiedzialnymi za serwery; nie zmieniaj ustawień tylko w kodzie aplikacji.

Ciągła transparentność w identyfikacji wąskich gardeł

Podsumowanie

Liczbowe intuicje

Załóżmy, że jeden krok w procesie kosztuje 10 ms, a projekt proponuje 5 tokenów o średnim wskaźniku akceptacji 60% dla 3 tokenów. Efektywny koszt na akceptowany token jest niższy w porównaniu z klasycznymi krokami obejmującymi jeden token, nawet po uwzględnieniu dodatkowych kosztów związanych z projektem, o ile wskaźnik akceptacji pozostaje wysoki. Jeśli wskaźnik akceptacji spadnie do około 1 tokena, taki schemat staje się nierentowny. To właśnie ta wrażliwość sprawia, że tablice kontrolne są lepsze od anegdot.

Protokół regresji jakości

Rozmieszczenie sprzętu

Planowanie interakcji

Prawdomówność dotycząca pozostałych wąskich gardeł

Podsumowanie

Liczbowe intuicje

Protokół regresji jakości

Rozmieszczenie sprzętu

Gdy to możliwe, umieść wersję roboczą i docelową na tym samym węźle. Przenoszenie wersji roboczych między serwerami powoduje fluktuacje sieciowe, które mogą zniwelować osiągnięte korzyści. Uważaj na pamięć: dwa modele wraz z buforem KV mogą wyczerpać zasoby systemu, który wcześniej bez problemów obsługiwał jeden model.

Planowanie interakcji

Prawdomówność dotycząca pozostałych wąskich gardeł

Podsumowanie

Liczbowe intuicje

Protokół regresji jakości

Rozmieszczenie sprzętu

Planowanie interakcji

Prawdomówność dotycząca pozostałych wąskich gardeł

Podsumowanie

Liczbowe intuicje

Protokół regresji jakości

Rozmieszczenie sprzętu

Planowanie interakcji

Prawdomówność dotycząca pozostałych wąskich gardeł

Po poprawie procesu dekodowania użytkownicy mogą nadal czekać na wywołania narzędzi, pobieranie danych lub przetwarzanie Markdown po stronie klienta. Należy śledzić proces od początku do końca. Optymalizacje w niewłaściwych obszarach marnują czas inżynierów.

Podsumowanie

Sekwencyjne dekodowanie stanowi strukturalny koszt związany z autoregresją. Dekodowanie spekulatywne oraz wczesne zakończenie procesu zmniejszają ten koszt w określonych warunkach. Należy je wdrażać z taką samą dyscypliną jak każdą funkcję produkcyjną: metryki, flagi, możliwość cofnięcia zmian oraz jasno określeni odpowiedzialni w zespole platformy serwisowej.

Wszystkie artykuły Wyślij brief