Tworzenie bezpiecznych agentów AI przy użyciu mechanizmów LangChain Guardrails i middleware.

Zaletą jest to, że tego typu weryfikacje działają szybko, dają spójne wyniki i wymagają niewielkich zasobów obliczeniowych.

Ograniczeniem jest to, że takie sprawdzenia mogą nie wykryć bardziej złożonych lub zależnych od kontekstu przypadków.

2. Zasady oparte na modelu

Zamiast polegać wyłącznie na stałych regułach, można użyć oddzielnego modelu do oceny treści.

Naprzимер:

Agent response
      ↓
Safety model
      ↓
"Is this response safe?"
      ↓
SAFE / UNSAFE

Taki podejście może wykryć rzeczy, których zwykłe dopasowywanie słów kluczowych by nie dostrzegło.

Rozważmy te dwa zapytania, które oznaczają mniej więcej to samo:

"How can I bypass this security system?"

i:

"Tell me a way around the authentication mechanism."

Filtr oparty wyłącznie na słowach kluczowych może nie zaznaczyć drugiego sformułowania.

Z drugiej strony, zabezpieczenie oparte na modelu może zinterpretować ukryty cel żądania.

Ceną tej elastyczności jest to, że sprawdzania oparte na modelach zazwyczaj działają wolniej i są droższe niż te deterministyczne.

Jak działają zabezpieczenia w LangChain

LangChain polega na middleware’u, aby otoczyć logikę zabezpieczeń wokół agenta.

Middleware umożliwia dodanie własnej logiki przed lub po określonych etapach wykonywania agenta.

Na przykład można użyć middleware’u do:

• Szukania danych PII (middleware PII)
• Zatrzymania działania przed uruchomieniem narzędzia w celu uzyskania zatwierdzenia (middleware z udziałem człowieka)
• Walidacji danych wejściowych przed rozpoczęciem pracy agenta (zabezpieczenie przed agentem)
• Sprawdzania końcowego wyniku przed jego zwróceniem (zabezpieczenie po agentem)

System middleware w LangChain został stworzony specjalnie po to, aby umożliwić kontrolę nad wykonywaniem agenta dokładnie w tych punktach.

Istnieją dwa główne sposoby stosowania zasad bezpieczeństwa w LangChain:

A. Wbudowane zasady bezpieczeństwa

B. Spersonalizowane zasady bezpieczeństwa

                    Guardrails in LangChain
                             │
                 ┌───────────┴───────────┐
                 │                       │
                 ▼                       ▼
          Built-in Guardrails      Custom Guardrails
                 │                       │
                 │                       │
                 ▼                       ▼
          Ready-to-use             Application-specific
           middleware                 middleware
                 │                       │
          ┌──────┴──────┐        ┌───────┴───────┐
          │             │        │               │
          ▼             ▼        ▼               ▼
         PII           HITL   Before-Agent   After-Agent
      handling       approval    guardrail      guardrail

A. Wbudowane zasady bezpieczeństwa w LangChain

LangChain dostarcza kilka gotowych do użycia zasad bezpieczeństwa, które nie wymagają żadnej dodatkowej konfiguracji.

Dwie z nich, opisane w dokumentacji biblioteki, to:

1. Rozpoznawanie PII
2. Człowiek w łańcuchu decyzyjnym

Rozważmy obie z nich.

1. Rozpoznawanie PII

LangChain zawiera middleware specjalnie zaprojektowany do wykrywania i obsługi Danych Osobowościowych (PII) pojawiających się w rozmowie.

Może to obejmować m.in.:

Email address
Credit card number
IP address
MAC address

Gdy agent ma dostęp do danych wrażliwych, zazwyczaj nie chce się, aby te dane zostały przekazane modelowi lub odsłonięte w odpowiedzi.

LangChain rozwiązuje ten problem za pomocą piiRedactionMiddleware().

Oto przykład:

import {
  createAgent,
  piiRedactionMiddleware,
} from "langchain";

const agent = createAgent({
  model: "gpt-5.5",
  tools: [customerServiceTool],

  middleware: [
    piiRedactionMiddleware({
      piiType: "email",
      strategy: "redact",
      applyToInput: true,
      applyToOutput: true,
    }),
  ],
});

const result = await agent.invoke({
  messages: [{
    role: "user",
    content: "My email is john.doe@example.com"
  }]
});

Załóżmy, że użytkownik wysyła:

My email is john.doe@example.com

Middleware przechwytuje i przepisuje te dane, zanim model je w ogóle zobaczy:

My email is [REDACTED_EMAIL]

Innymi słowy, model pracuje z wyczyszczonego tekstem zastępczym, a nie z surowymi danymi wrażliwymi.

Uwaga: Ustawienie applyToOutput: true zapewnia, że nawet jeśli model przypadkowo wygeneruje dane PII w swojej odpowiedzi, middleware usunie je przed tym, jak odpowiedź dotrze do użytkownika. Jeśli twoje narzędzia mogą wyciekać dane PII w swoich wynikach, applyToToolResults: true rozszerza tę samą ochronę również na wyniki narzędzi.

Strategie obsługi danych PII

LangChain wspiera cztery różne sposoby radzenia sobie z wykrytymi danymi PII:

Aby zobaczyć różnice, zastosujmy każdą strategię do tego samego przykładowego wprowadzenia.

Załóżmy, że użytkownik wpisze:

My email is john.doe@example.com

1. redact

Za pomocą redact wszystkie wykryte dane PII są całkowicie zastąpione ogólnym zamiennikiem.

piiRedactionMiddleware({
  piiType: "email",
  strategy: "redact",
  applyToInput: true,
});

To, co model faktycznie otrzymuje, to:

My email is [REDACTED_EMAIL]

Ta strategia nadaje się do sytuacji, gdy model rzeczywiście nie musi znać wartości podstawowej.

2. mask

Strategia mask ukrywa część wartości, pozostawiając wystarczająco dużo widocznego tekstu dla kontekstu.

piiRedactionMiddleware({
  piiType: "email",
  strategy: "mask",
  applyToInput: true,
});

E-mail może wyglądać w ten sposób:

My email is j***@example.com

Jest to przydatne, gdy zarówno model, jak i użytkownik końcowy potrzebują częściowego odniesienia do danych, bez konieczności ujawniania ich w całości.

3. hash

hash zastępuje dane osobowe spójną, deterministyczną wartością hasza.

piiRedactionMiddleware({
  piiType: "email",
  strategy: "hash",
  applyToInput: true,
});

Zmodyfikowany e-mail może wyglądać mniej więcej tak:

My email is 8f14e45fceea167a5a36dedd4bea2543...

Ponieważ haszowanie jest deterministyczne, identyczne dane zawsze dają identyczne hashe. Dzięki temu można śledzić lub porównywać powtarzające się wystąpienia tej samej wartości, nie ujawniając przy tym oryginalnych danych.

4. block

W odróżnieniu od pozostałych trzech metod, block w ogóle nie przetwarza danych osobowych — po prostu odmawia obsługi żądania, gdy tylko zostanie wykryty taki typ danych.

Na przykład można skonfigurować specjalny detektor do wykrywania kluczy API:

piiRedactionMiddleware({
  piiType: "api_key",
  detector: /sk-[a-zA-Z0-9]{32}/,
  strategy: "block",
  applyToInput: true,
});

Jeśli użytkownik następnie wyśle:

My API key is sk-abcdefghijklmnopqrstuvwxyz123456

middleware rozpoznaje wzorzec klucza API i zatrzymuje żądanie, zanim wartość może zostać dalej przekazana.

Ta strategia nadaje się do przypadków, gdy określone kategorie danych wrażliwych — klucze API, dane uwierzytelniające oraz podobne tajemnice — w ogóle nie powinny trafić do procesu obsługi agenta.

2. Ludzki element w procesie

Pewne operacje niosą zbyt duże ryzyko, by mogły być w całości przekazane autonomicznemu agentowi.

Rozważmy takie działania jak:

delete production database
send an external email
make a financial transaction
modify production data

Zamiast całkowicie zabraniać tych działań, można je skierować przez etap zatwierdzenia przez człowieka.

Otrzymany tok wygląda w ten sposób:

Agent
  ↓
Tool call
  ↓
Guardrail
  ↓
Human approval
  ↓
┌───────────────┐
│               │
Approved      Rejected
│               │
↓               ↓
Execute        Stop

LangChain oferuje humanInTheLoopMiddleware() do wdrożenia tego wzorca.

Na przykład:

import { createAgent, humanInTheLoopMiddleware } from "langchain";
import { MemorySaver, Command } from "@langchain/langgraph";

const agent = createAgent({
  model: "gpt-5.5",
  tools: [
    searchTool,
    sendEmailTool,
    deleteDatabaseTool,
  ],
  middleware: [
    humanInTheLoopMiddleware({
      interruptOn: {
        send_email: {
          allowAccept: true,
          allowEdit: true,
          allowRespond: true,
        },
        delete_database: {
          allowAccept: true,
          allowEdit: true,
          allowRespond: true,
        },
        search: false,
      },
    }),
  ],
  // A checkpointer is required so the paused run can be resumed later
  checkpointer: new MemorySaver(),
});

Gdy to jest wdrożone, agent zatrzymuje się przed wykonaniem send_email lub delete_database i czeka na decyzję człowieka. Aby wznowić wykonanie później, wywołanie wymaga zarówno ID wątku, jak i Command:

const config = { configurable: { thread_id: "some_id" } };
// First call pauses and waits for approval
await agent.invoke(
  { messages: [{ role: "user", content: "Send an email to the team" }] },
  config
);
// Resume after a human approves the tool call
await agent.invoke(
  new Command({ resume: { decisions: [{ type: "approve" }] } }),
  config
);

Ważne: bez checkpointer i thread_id middleware nie ma czego kontynuować, a mechanizm pauzy i zatwierdzenia po prostu nie będzie działał. To zdecydowanie najczęstszy błąd konfiguracyjny.

Tutaj konfiguracja faktycznie stanowi:

search → automatically allowed
send_email → require human approval
delete_database → require human approval

Ten wzorzec okazuje się szczególnie przydatny dla agentów działających w środowiskach produkcyjnych.

Jeśli chcesz lepiej poznać wzorzec human-in-the-loop, osobny praktyczny przewodnik opisuje dokładnie, w jaki sposób graf zatrzymuje się za pomocą interrupt(), czeka na decyzję człowieka, a następnie kontynuuje wykonywanie przez Command.

B. Dostosowane zasady bezpieczeństwa

Middleware LangChain dostępny „od ręki” nie będzie odpowiadał każdemu scenariuszowi, z którym boryka się twoja aplikacja.

Gdy twoje wymagania wykraczają poza to, co jest wbudowane, LangChain umożliwia tworzenie własnego middleware oraz integrację dostosowanego zachowania zasad bezpieczeństwa.

Dwa hooki dotyczące cyklu życia są szczególnie przydatne w tym celu:

beforeAgent
afterAgent

Te hooki dają możliwość wstrzyknięcia logiki zasad bezpieczeństwa w określonych momentach podczas działania agenta.

1. Zasady bezpieczeństwa przed uruchomieniem agenta

Hook beforeAgent uruchamia się na samym początku wywołania agenta. Można go użyć do stworzenia zasady bezpieczeństwa, która sprawdza lub filtrowa żądanie przed tym, jak agent zacznie je przetwarzać.

Typowe przypadki użycia to:

• Autoryzacja
• Ograniczenie szybkości wywołań
• Filtrowanie danych wejściowych
• Odrzucanie nieodpowiednich żądań
• Weryfikacje ograniczone do sesji

Oto ilustracja:

import { createMiddleware, AIMessage } from "langchain";

const sensitiveDataFilterMiddleware = (sensitiveKeywords: string[]) => {
  const keywords = sensitiveKeywords.map((kw) => kw.toLowerCase());

  return createMiddleware({
    name: "SensitiveDataFilterMiddleware",

    beforeAgent: {
      hook: (state) => {
        // Check if messages exist
        if (!state.messages || state.messages.length === 0) {
          return;
        }

        // Get the first user message
        const firstMessage = state.messages[0];

        // Make sure the message is from the user
        if (firstMessage._getType() !== "human") {
          return;
        }

        const content = firstMessage.content.toString().toLowerCase();

        // Check for sensitive keywords
        for (const keyword of keywords) {
          if (content.includes(keyword)) {
            // Stop the agent before it starts processing
            return {
              messages: [
                new AIMessage(
                  "I cannot process requests containing sensitive information. " +
                  "Please remove passwords, API keys, or secrets and try again."
                ),
              ],
              jumpTo: "end",
            };
          }
        }

        // No sensitive content found
        return;
      },

      canJumpTo: ["end"],
    },
  });
};


// Create the agent
import { createAgent } from "langchain";

const agent = createAgent({
  model: "gpt-5.5",
  tools: [searchTool, calculatorTool],

  middleware: [
    sensitiveDataFilterMiddleware([
      "password",
      "api_key",
      "secret",
      "private_key",
    ]),
  ],
});


// This request will be blocked
const result = await agent.invoke({
  messages: [
    {
      role: "user",
      content: "Show me how to store my production password securely.",
    },
  ],
});

console.log(result);

Przepływ:

                         User Request
                              │
                              ▼
                  ┌──────────────────────┐
                  │   beforeAgent Hook   │
                  │                      │
                  │ Check user message   │
                  │ for sensitive words │
                  └──────────┬───────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │ Sensitive       │
                    │ keyword found?  │
                    └───────┬─────────┘
                            │
                   ┌────────┴────────┐
                   │                 │
                  YES                NO
                   │                 │
                   ▼                 ▼
        ┌──────────────────┐   ┌──────────────┐
        │ Return blocked   │   │ Continue to  │
        │ AIMessage        │   │ the agent    │
        └────────┬─────────┘   └───────┬──────┘
                 │                     │
                 ▼                     ▼
          jumpTo: "end"          Agent executes
                 │                     │
                 ▼                     ▼
           Final Response        Final Response

Gdy ten hook jest aktywny, problematyczne żądanie zostaje zatrzymane, zanim agent zdąży uruchomić lub wywołać jakiekolwiek narzędzia.

2. Zasady bezpieczeństwa po uruchomieniu agenta

Hook afterAgent uruchamia się po zakończeniu pracy agenta. Pozwala to na implementację zasady bezpieczeństwa, która sprawdza lub filtrowa ostateczną odpowiedź agenta przed jej dostarczeniem użytkownikowi.

Powszechne zastosowania obejmują:

• Kontrole bezpieczeństwa

Jako przykład można skierować odpowiedź przez drugi model, którego jedynym zadaniem jest jej ocena:

import {
  createMiddleware,
  AIMessage,
  initChatModel,
} from "langchain";

const toxicityGuardrailMiddleware = () => {
  // Model used only for toxicity evaluation
  const evaluatorModel = initChatModel("gpt-5.4-mini");

  return createMiddleware({
    name: "ToxicityGuardrailMiddleware",

    afterAgent: {
      hook: async (state) => {
        // Get the final AI response
        if (!state.messages || state.messages.length === 0) {
          return;
        }

        const lastMessage =
          state.messages[state.messages.length - 1];

        if (lastMessage._getType() !== "ai") {
          return;
        }

        const response = lastMessage.content.toString();

        // Ask the evaluator model to check for toxicity
        const evaluationPrompt = `
You are a toxicity detection system.

Analyze the following AI response and determine
whether it contains toxic, abusive, hateful, or
harassing language.

Respond with ONLY:
SAFE
or
TOXIC

AI response:
${response}
`;

        const evaluation = await evaluatorModel.invoke([          {            role: "user",            content: evaluationPrompt,          },        ]);

        const result = evaluation.content
          .toString()
          .trim()
          .toUpperCase();

        // Replace the response if it is toxic
        if (result === "TOXIC") {
          return {
            messages: [
              new AIMessage(
                "I'm unable to provide that response because it contains inappropriate language."
              ),
            ],
            jumpTo: "end",
          };
        }

        return;
      },

      canJumpTo: ["end"],
    },
  });
};


// Create the agent
import { createAgent } from "langchain";

const agent = createAgent({
  model: "gpt-5.5",

  tools: [
    searchTool,
    calculatorTool,
  ],

  middleware: [
    toxicityGuardrailMiddleware(),
  ],
});


// Invoke the agent
const result = await agent.invoke({
  messages: [
    {
      role: "user",
      content: "Give me a response to this angry customer.",
    },
  ],
});

console.log(result);

User
 ↓
Main Agent (GPT-5.5)
 ↓
Generates response
 ↓
afterAgent hook
 ↓
Evaluator Model (GPT-5.4-mini)
 ↓
┌───────────────┐
│ Is it toxic?  │
└───────┬───────┘
        │
    ┌───┴───┐
    ↓       ↓
  SAFE     TOXIC
    ↓       ↓
Return    Replace
response  response

Głównym wnioskiem jest to, że nigdy nie należy automatycznie ufać wynikom agenta. Zamiast tego wysyła się wygenerowaną odpowiedź do modelu oceniającego, którego zadaniem jest sprawdzenie jej pod kątem Twoich kryteriów bezpieczeństwa przed przekazaniem jej użytkownikowi.

Łączenie kilku zabezpieczeń

Różne fazy wykonywania zadań przez agenta wymagają różnych rodzajów zabezpieczeń. Rozważmy następującą sekwencję:

1. Input filtering
2. PII protection
3. Tool approval
4. Output safety check

LangChain umożliwia jednoczesne dołączenie kilku elementów middleware do pojedynczego agenta.

Oto przykład:

const agent = createAgent({
  model: "gpt-5.5",
  tools: [
    searchTool,
    sendEmailTool,
  ],
  middleware: [
    // 1. Before-agent guardrail for input filtering
    sensitiveDataFilterMiddleware([
      "password",
      "api_key",
      "secret",
      "private_key",
    ]),
    // 2. Built-in PII protection middleware
    piiRedactionMiddleware({
      piiType: "email",
      strategy: "redact",
      applyToInput: true,
      applyToOutput: true,
    }),
    // 3. Built-in Human approval middleware for sensitive tools
    humanInTheLoopMiddleware({
      interruptOn: {
        send_email: {
          allowAccept: true,
          allowEdit: true,
          allowRespond: true,
        },
      },
    }),
    // 4. After-agent guardrail
    toxicityGuardrailMiddleware(),
  ],
});

Każda warstwa middleware jest odpowiedzialna za ochronę określonej części ścieżki wykonywania agenta.

W całości przepływ wygląda w ten sposób:

                         User Request
                              │
                              ▼
                  ┌──────────────────────┐
                  │ Before-agent         │
                  │ guardrail            │
                  │                      │
                  │ Input filtering      │
                  └──────────┬───────────┘
                             │
                             ▼
                  ┌──────────────────────┐
                  │ PII protection       │
                  │                      │
                  │ Redact sensitive     │
                  │ information          │
                  └──────────┬───────────┘
                             │
                             ▼
                         AI Agent
                             │
                             ▼
                       Tool call?
                        /       \
                      No         Yes
                      │           │
                      │           ▼
                      │    ┌───────────────┐
                      │    │ Human approval│
                      │    └───────┬───────┘
                      │            │
                      │       ┌────┴────┐
                      │       │         │
                      │    Approved   Rejected
                      │       │         │
                      │       ▼         ▼
                      │   Execute      Stop
                      │       │
                      └───────┤
                              ▼
                       Agent response
                              │
                              ▼
                  ┌──────────────────────┐
                  │ After-agent          │
                  │ guardrail            │
                  │                      │
                  │ Toxicity check       │
                  │ using evaluator model│
                  └──────────┬───────────┘
                             │
                        ┌────┴────┐
                        │         │
                       SAFE      TOXIC
                        │         │
                        ▼         ▼
                   Return      Replace
                   response    response

To tworzy warstwową strategię ochrony dla agenta.

Główna idea polega na tym, że każda z tych warstw ochronnych jest odpowiedzialna za inny punkt kontrolny:

• Warstwa ochronna przed agentem weryfikuje przychodzące żądanie.
• Middleware do ochrony danych osobowych chroni poufne informacje.
• Przegląd przez człowieka blokuje ryzykowne wywołania narzędzi, dopóki osoba nie je zatwierdzi.
• Warstwa ochronna po agentem sprawdza końcową odpowiedź przed jej dostarczeniem użytkownikowi.

Zamiast polegać na jednym mechanizmie bezpieczeństwa, stosuje się kilka warstw ochronnych, aby agent był lepiej chroniony na każdym etapie.

Zasady bezpieczeństwa to nie tylko kwestia ochrony

Gdy ludzie słyszą termin „zasady bezpieczeństwa”, zwykle wyobrażają sobie blokowanie treści szkodliwych lub obraźliwych.

Jednak w systemach produkcyjnych zasady te służą również do egzekwowania logiki biznesowej oraz polityk specyficznych dla aplikacji.

Naprzимер:

Customer support agent

Can:
✓ Search orders
✓ Check delivery status

Cannot:
✗ Refund more than ₹10,000
✗ Delete customer account
✗ Change payment details

Te zasady nie mają nic wspólnego z wykrywaniem treści szkodliwych.

Odpowiadają one politykom aplikacji, które określają granice tego, co agent może robić.

Ponieważ model językowy podejmuje decyzje dynamicznie w trakcie działania, potrzebny jest niezawodny punkt egzekwowania zasad, które muszą obowiązywać niezależnie od decyzji podejmowanych przez model.

Uwaga: LLM decyduje, co chce zrobić; ograniczenia określają to, co aplikacja faktycznie mu pozwala robić.

Ostateczne refleksje

Budowa agenta AI wymaga czegoś więcej niż po prostu podłączenia LLM do kilku narzędzi.

Gdy agent zaczyna obsługiwać rzeczywiste żądania użytkowników i interakcjonować z prawdziwymi systemami, konieczne są jasne granice jego zachowania. Właśnie tę rolę pełnią ograniczenia.

LangChain dostarcza kilku elementów budulcowych do tego celu:

• Deterministyczne ograniczenia dla reguł, które muszą być przewidywalne
• Ograniczenia oparte na modelach dla sprawdzeń zależnych od znaczenia i kontekstu
• Środkowisko PII do obsługi informacji wrażliwych
• Środkowisko z udziałem człowieka dla działań o rzeczywistych konsekwencjach
• Środkowisko przed agentem do sprawdzeń na poziomie wejścia i sesji
• Środkowisko po agentem do weryfikacji końcowego wyniku