Garde-fous et examen humain

Utilisez des garde-fous pour automatiser les contrôles et faites intervenir une personne pour les décisions d’approbation. Ensemble, ces mécanismes déterminent quand l’exécution doit se poursuivre, se mettre en pause ou s’arrêter.

• Les garde-fous valident automatiquement les entrées, les sorties ou le comportement des outils.
• L’examen humain suspend l’exécution pour qu’une personne ou une règle d’approbation puisse autoriser ou refuser une action sensible.

Choisissez le contrôle adapté

Ajoutez un garde-fou bloquant

Utilisez des garde-fous d’entrée pour effectuer une vérification rapide avant de lancer la partie du workflow qui coûte cher ou qui produit des effets de bord.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39import { 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;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57import asyncio

from pydantic import BaseModel

from agents import (
    Agent,
    GuardrailFunctionOutput,
    InputGuardrailTripwireTriggered,
    RunContextWrapper,
    Runner,
    TResponseInputItem,
    input_guardrail,
)


class MathHomeworkOutput(BaseModel):
    is_math_homework: bool
    reasoning: str


guardrail_agent = Agent(
    name="Homework check",
    instructions="Detect whether the user is asking for math homework help.",
    output_type=MathHomeworkOutput,
)


# Validate input before starting the support agent.
@input_guardrail(run_in_parallel=False)
async def math_guardrail(
    ctx: RunContextWrapper[None],
    agent: Agent,
    input: str | list[TResponseInputItem],
) -> GuardrailFunctionOutput:
    result = await Runner.run(guardrail_agent, input, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=result.final_output.is_math_homework,
    )


agent = Agent(
    name="Customer support",
    instructions="Help customers with support questions.",
    input_guardrails=[math_guardrail],
)


async def main() -> None:
    try:
        await Runner.run(agent, "Can you solve 2x + 3 = 11 for me?")
    except InputGuardrailTripwireTriggered:
        print("Guardrail blocked the request.")


if __name__ == "__main__":
    asyncio.run(main())

Choisissez une exécution bloquante si le lancement de l’agent principal présente un coût ou un risque trop élevé. Exécutez les garde-fous en parallèle si la réduction de la latence prime, quitte à lancer des opérations qui pourraient s’avérer inutiles.

Suspendez l’exécution pour un examen humain

Les approbations permettent de soumettre les appels d’outils à un examen humain. Le modèle peut toujours déterminer qu’une action est nécessaire, mais l’exécution reste en pause jusqu’à ce que vous l’approuviez ou la refusiez.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31import { 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);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32import asyncio

from agents import Agent, Runner, function_tool


@function_tool(needs_approval=True)
async def cancel_order(order_id: int) -> str:
    return f"Cancelled order {order_id}"


agent = Agent(
    name="Support agent",
    instructions="Use cancel_order to handle cancellation requests.",
    tools=[cancel_order],
)


async def main() -> None:
    result = await Runner.run(agent, "Cancel order 123.")

    if result.interruptions:
        state = result.to_state()
        for interruption in result.interruptions:
            print("Approval required:", interruption.name)
            state.approve(interruption)
        result = await Runner.run(agent, state)

    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

Ce mécanisme d’interruption s’applique aussi lorsque l’outil soumis à approbation intervient plus loin dans le workflow, par exemple après un transfert à un autre agent ou dans un appel imbriqué à agent.asTool().

Cycle d’approbation

Lorsqu’un appel d’outil nécessite un examen, le SDK suit toujours les mêmes étapes :

1. L’exécution enregistre une interruption pour approbation au lieu d’appeler l’outil.
2. Le résultat contient interruptions ainsi qu’un state qui permet de reprendre l’exécution.
3. Votre application approuve ou refuse les demandes en attente.
4. Vous reprenez la même exécution à partir de state sans lancer un nouveau tour de conversation avec l’utilisateur.

Si l’examen risque de prendre du temps, sérialisez state, enregistrez-le et reprenez l’exécution plus tard. Il s’agit toujours de la même exécution.

Portée des garde-fous dans le workflow

Les garde-fous définis au niveau de l’agent ont une portée limitée :

• Les garde-fous d’entrée s’appliquent uniquement au premier agent de la chaîne.
• Les garde-fous de sortie s’appliquent uniquement à l’agent qui produit la sortie finale.
• Les garde-fous d’outil s’appliquent aux outils de type fonction auxquels ils sont associés.

Si un agent supervise le workflow et que chaque appel à un outil personnalisé doit être vérifié, les garde-fous d’entrée ou de sortie de l’agent ne suffisent pas. Placez le contrôle au niveau de l’outil qui produit l’effet de bord.

Examinez les actions de cybersécurité avant leur exécution

Dans les workflows de cybersécurité autorisés, évaluez chaque appel d’outil sensible avant son exécution. Utilisez les garde-fous d’outil et les interruptions pour approbation afin de faire respecter le périmètre défini par écrit pour la mission, au niveau même où se produisent les effets de bord :

1. Vérifiez que la cible et l’action proposées, les arguments de l’outil, l’identité de l’appelant et la période d’intervention respectent le périmètre approuvé.
2. Transmettez l’action exacte proposée à un composant distinct chargé d’appliquer les règles ou à une personne chargée de l’examen. Fournissez uniquement le contexte nécessaire à son évaluation.
3. Refusez tout accès aux hôtes hors périmètre. Bloquez le vol d’identifiants, les mécanismes de persistance, l’exfiltration de données, les modifications destructrices, l’accès à la production et les tentatives de contournement des règles.
4. Suspendez les actions ambiguës ou à haut risque et attendez une approbation humaine explicite avant d’exécuter l’outil.
5. Faites respecter des limites indépendantes pour le système de fichiers, le réseau, les identités et les projets. Consignez les décisions et les résultats d’exécution. Bloquez l’action si le délai d’examen expire ou si l’examen devient impossible.

Les applications qui utilisent l’API Responses ou le SDK Agents ne bénéficient pas automatiquement de la Révision automatique de Codex. Intégrez l’examen des actions et l’application des décisions à votre propre harnais. La politique d’examen open source de Codex illustre une approche possible. Consultez Modèles et accès de confiance pour connaître les conditions d’accès autorisé aux modèles et Configuration recommandée pour préparer votre intervention en toute sécurité.

Le streaming et l’examen différé utilisent le même modèle d’état

Le streaming utilise le même système d’approbation. Si une exécution en streaming se met en pause, attendez qu’elle se stabilise, examinez interruptions, approuvez ou refusez les demandes, puis reprenez l’exécution à partir du même state. Si l’examen a lieu plus tard, enregistrez l’état sérialisé et reprenez la même exécution une fois la décision rendue.

Étapes suivantes

Une fois la portée des contrôles définie, consultez le guide consacré à l’environnement d’exécution ou aux outils concernés.