Nutze Guardrails für automatische Prüfungen und die menschliche Prüfung für Entscheidungen über Genehmigungen. Zusammen legen sie fest, wann ein Lauf fortgesetzt, unterbrochen oder beendet werden soll.
- Guardrails prüfen automatisch Eingaben, Ausgaben oder das Verhalten von Tools.
- Die menschliche Prüfung unterbricht den Lauf, damit eine Person oder ein richtlinienbasiertes System eine sensible Aktion genehmigen oder ablehnen kann.
Die passende Kontrolle auswählen
| Anwendungsfall | Empfohlene Kontrolle |
|---|---|
| Unzulässige Anfragen blockieren, bevor das Hauptmodell startet | Eingabe-Guardrails |
| Die endgültige Ausgabe prüfen oder sensible Inhalte darin schwärzen, bevor sie das System verlässt | Ausgabe-Guardrails |
| Argumente oder Ergebnisse beim Aufruf eines Funktionstools prüfen | Tool-Guardrails |
| Den Lauf vor Aktionen mit Nebenwirkungen unterbrechen, etwa vor Stornierungen, Änderungen, Shell-Befehlen oder sensiblen MCP-Aktionen | Genehmigung durch eine Person |
Einen blockierenden Guardrail hinzufügen
Verwende Eingabe-Guardrails, wenn du eine schnelle Prüfung durchführen möchtest, bevor ein aufwendiger Workflow-Schritt oder ein Schritt mit Nebenwirkungen beginnt.
import { Agent, InputGuardrailTripwireTriggered, run } from "@openai/agents";
import { z } from "zod";
const guardrailAgent = new Agent({
name: "Homework check",
instructions: "Detect whether the user is asking for math homework help.",
outputType: z.object({
isMathHomework: z.boolean(),
reasoning: z.string(),
}),
});
const agent = new Agent({
name: "Customer support",
instructions: "Help customers with support questions.",
inputGuardrails: [
{
name: "Math homework guardrail",
runInParallel: false,
async execute({ input, context }) {
const result = await run(guardrailAgent, input, { context });
return {
outputInfo: result.finalOutput,
tripwireTriggered: result.finalOutput?.isMathHomework === true,
};
},
},
],
});
try {
await run(agent, "Can you solve 2x + 3 = 11 for me?");
} catch (error) {
if (error instanceof InputGuardrailTripwireTriggered) {
console.log("Guardrail blocked the request.");
} else {
throw error;
}
}Lass den Guardrail blockierend laufen, wenn es zu teuer oder zu riskant wäre, den Hauptagenten schon vor Abschluss der Prüfung zu starten. Führe Guardrails parallel aus, wenn eine geringe Latenz wichtiger ist, als möglicherweise unnötige Arbeit zu vermeiden.
Den Lauf zur menschlichen Prüfung unterbrechen
Über Genehmigungen kannst du Menschen in die Entscheidung über Tool-Aufrufe einbeziehen. Das Modell kann weiterhin entscheiden, dass eine Aktion erforderlich ist. Der Lauf pausiert jedoch, bis du die Aktion genehmigst oder ablehnst.
import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";
const cancelOrder = tool({
name: "cancel_order",
description: "Cancel a customer order.",
parameters: z.object({ orderId: z.number() }),
needsApproval: true,
async execute({ orderId }) {
return `Cancelled order ${orderId}`;
},
});
const agent = new Agent({
name: "Support agent",
instructions: "Use cancel_order to handle cancellation requests.",
tools: [cancelOrder],
});
let result = await run(agent, "Cancel order 123.");
if (result.interruptions?.length) {
const state = result.state;
for (const interruption of result.interruptions) {
console.log(`Approval required: ${interruption.name}`);
state.approve(interruption);
}
result = await run(agent, state);
}
console.log(result.finalOutput);Die Unterbrechung funktioniert genauso, wenn das Tool, dessen Aufruf eine Genehmigung erfordert, erst später im Workflow zum Einsatz kommt, etwa nach einer Übergabe oder innerhalb eines verschachtelten Aufrufs von agent.asTool()
Ablauf einer Genehmigung
Wenn ein Tool-Aufruf geprüft werden muss, läuft die Genehmigung im SDK immer gleich ab:
- Der Lauf vermerkt, dass er für eine Genehmigung unterbrochen wurde, und führt das Tool vorerst nicht aus.
- Das Ergebnis enthält
interruptionssowie einenstate, mit dem sich der Lauf fortsetzen lässt. - Deine Anwendung genehmigt die ausstehenden Aufrufe oder lehnt sie ab.
- Du setzt denselben Lauf anhand von
statefort, ohne eine neue Gesprächsrunde zu beginnen.
Wenn die Prüfung länger dauern könnte, serialisiere state und speichere ihn. So kannst du denselben Lauf später fortsetzen.
Geltungsbereich der Guardrails im Workflow
Guardrails auf Agentenebene greifen nur an bestimmten Stellen:
- Eingabe-Guardrails laufen nur für den ersten Agenten in der Kette.
- Ausgabe-Guardrails laufen nur für den Agenten, der die endgültige Ausgabe erzeugt.
- Tool-Guardrails greifen bei Aufrufen der Funktionstools, denen sie zugeordnet sind.
Wenn in einem Workflow mit einem steuernden Agenten jeder Aufruf eines benutzerdefinierten Tools geprüft werden muss, reichen Eingabe- oder Ausgabe-Guardrails auf Agentenebene allein nicht aus. Führe die Prüfung direkt bei dem Tool durch, das die Nebenwirkung auslöst.
Aktionen im Bereich Cybersicherheit vor der Ausführung prüfen
Prüfe in autorisierten Cybersicherheits-Workflows jeden sensiblen Tool-Aufruf vor der Ausführung. Setze Tool-Guardrails ein und unterbrich den Lauf bei Bedarf für eine Genehmigung. So setzt du die schriftlich festgelegten Grenzen des Auftrags dort durch, wo Nebenwirkungen auftreten:
- Gleiche das vorgeschlagene Ziel, die geplante Aktion, die Tool-Argumente, die Identität hinter dem Aufruf und das Einsatzzeitfenster mit dem genehmigten Auftragsumfang ab.
- Übermittle einer separaten Komponente zur Richtlinienprüfung oder einer prüfenden Person die genaue geplante Aktion und nur den Kontext, der für die Bewertung erforderlich ist.
- Blockiere Zugriffe auf Hosts außerhalb des genehmigten Umfangs, den Diebstahl von Zugangsdaten, die Einrichtung dauerhafter Zugänge, Datenexfiltration, destruktive Änderungen, Zugriffe auf Produktivsysteme und Versuche, Richtlinien zu umgehen.
- Halte unklare oder risikoreiche Aktionen an, bis eine Person sie ausdrücklich genehmigt hat. Erst dann darf das Tool ausgeführt werden.
- Setze für Dateisystem, Netzwerk, Identitäten und Projekte jeweils unabhängige Zugriffsgrenzen durch. Protokolliere Entscheidungen und Ausführungsergebnisse. Blockiere die Ausführung, wenn die Prüffrist abläuft oder die Prüfung nicht mehr verfügbar ist.
Anwendungen, die die Responses API oder das Agents SDK nutzen, übernehmen die Automatische Überprüfung von Codex nicht automatisch. Ergänze deinen eigenen Harness um die Prüfung und Durchsetzung der Richtlinien. Die quelloffene Richtlinie für die Prüfung durch Codex zeigt einen möglichen Ansatz. Informationen zum genehmigten Modellzugriff findest du im Leitfaden Modelle und vertrauenswürdiger Zugriff. Wie du den Einsatz sicher vorbereitest, erfährst du im Leitfaden Empfohlene Konfiguration.
Streaming und spätere Prüfung nutzen dasselbe Zustandsmodell
Auch beim Streaming gilt dasselbe Genehmigungsverfahren. Wenn ein Lauf beim Streaming pausiert, warte, bis die Unterbrechung abgeschlossen ist. Prüfe dann interruptions, entscheide über die ausstehenden Genehmigungen und setze den Lauf mit demselben state fort. Erfolgt die Prüfung erst später, speichere den serialisierten Zustand und setze denselben Lauf fort, sobald die Entscheidung vorliegt.
Nächste Schritte
Wenn du weißt, wo die einzelnen Kontrollen greifen, lies den passenden Leitfaden zur Laufzeitumgebung oder zu den Tool-Schnittstellen.
Erfahre, wie die Ausführungsschleife Unterbrechungen und die anschließende Fortsetzung eines Laufs handhabt.
Erfahre, welche Ergebnisdaten deine Anwendung erhält, wenn ein Lauf pausiert.
Entscheide, an welchen Tool-Schnittstellen eine Prüfung oder Genehmigung erforderlich ist, bevor Nebenwirkungen auftreten.