Guardrails w praktyce: projektowanie wielopoziomowej moderacji w OpenAI Agents JS

1. Dlaczego potrzebujemy kaskadowych guardrailów?

Dokumentacja OpenAI Agents SDK dla JavaScript podkreśla, że strażnicy (guardrails) mogą działać na wejściu, wyjściu oraz w trakcie pracy agenta. W praktyce warto zbudować kaskadę:

1. InputGuardrail – filtruje niepożądane tematy jeszcze przed uruchomieniem agenta.
2. Output Guardrail – upewnia się, że odpowiedź spełnia standardy (bez danych wrażliwych, z poprawnym formatem).
3. Manual override – operator może zatwierdzić odrzucone zapytanie poprzez state.approve(...).

2. Przygotowanie modeli Zod

import { Agent, InputGuardrail, GuardrailFunctionOutput } from "@openai/agents";
import { z } from "zod";

const TopicVerdict = z.object({
  allowed: z.boolean(),
  reason: z.string(),
});

const OutputCheck = z.object({
  safe: z.boolean(),
  redacted: z.boolean(),
});

3. Agent strażnik i InputGuardrail

const guardrailAgent = new Agent({
  name: "Guardrail Triage",
  instructions: "Sprawdź, czy pytanie dotyczy wsparcia produktowego lub billingowego.",
  outputType: TopicVerdict,
});

const inputGuardrail = new InputGuardrail({
  guardrailFunction: async (ctx, agent, input) => {
    const result = await guardrailAgent.run({ input });
    const verdict = result.finalOutput;
    return {
      outputInfo: verdict,
      tripwireTriggered: !verdict?.allowed,
    } satisfies GuardrailFunctionOutput<z.infer<typeof TopicVerdict>>;
  },
});

Jeżeli strażnik zablokuje zapytanie, SDK zwróci InputGuardrailTripwireTriggered, dzięki czemu możemy wyświetlić użytkownikowi uprzejmy komunikat.

4. Dodanie guardraila wyjściowego

const outputGuardrailAgent = new Agent({
  name: "Output Auditor",
  instructions: "Sprawdź, czy odpowiedź jest zgodna z polityką, ma poprawny ton i nie zawiera danych wrażliwych.",
  outputType: OutputCheck,
});

const supportAgent = new Agent({
  name: "Support Specialist",
  instructions: "Rozwiązuj zgłoszenia produktowe w jasny, uprzejmy sposób.",
  inputGuardrails: [inputGuardrail],
  outputGuardrails: [
    async (ctx, agent, output) => {
      const audit = await outputGuardrailAgent.run({ input: output });
      return {
        outputInfo: audit.finalOutput,
        tripwireTriggered: !audit.finalOutput?.safe,
      };
    },
  ],
});

5. Obsługa wyjątków i manualne override

import {
  InputGuardrailTripwireTriggered,
  GuardrailExecutionError,
} from "@openai/agents";

async function handleRequest(prompt: string) {
  try {
    const result = await supportAgent.run({ input: prompt });
    return result.finalOutput;
  } catch (error) {
    if (error instanceof InputGuardrailTripwireTriggered) {
      return `Zgłoszenie odrzucone: ${error.message}`;
    }
    if (error instanceof GuardrailExecutionError) {
      console.error("Guardrail error:", error.state);
      return "Wystąpił błąd moderacji. Zgłoś sprawę operatorowi.";
    }
    throw error;
  }
}

W przypadku narzędzi oznaczonych needsApproval: true, result.interruptions będzie zawierało listę oczekujących zgód:

const run = await supportAgent.run({ input: "Usuń konto użytkownika" });

for (const approval of run.interruptions ?? []) {
  // logika biznesowa: np. sprawdź uprawnienia operatora
  run.state.approve(approval, { alwaysApprove: false });
}

const continued = await supportAgent.run({ state: run.state });

6. Dobre praktyki

• Loguj outputInfo strażników – dane diagnostyczne przydają się do szkoleń i audytów.
• Kaskaduj guardraile – możesz dodać kolejne poziomy (np. sprawdzanie formatu JSON).
• Zachowaj spójność – ten sam model Zod (TopicVerdict) wykorzystaj w Node/API, aby walidować override operatora.

Rezultat to wielopoziomowy system moderacji, który automatycznie odrzuca niepożądane pytania, pilnuje jakości odpowiedzi i pozwala ludziom w wyjątkowych przypadkach przejąć kontrolę.

📚 Dokumentacja i Zasoby

Oficjalna Dokumentacja

• OpenAI Agents SDK - JavaScript
• OpenAI Agents SDK - Python
• Model Context Protocol

Powiązane Artykuły

• OpenAI Agents JS - Orkiestracja
• MCP (Model Context Protocol)