Salvaguardas y revisión humana

Usa salvaguardas para las comprobaciones automáticas y la revisión humana para decidir si se aprueba una acción. En conjunto, estos controles definen cuándo debe continuar, pausarse o detenerse una ejecución.

• Las salvaguardas validan automáticamente la entrada, la salida o el comportamiento de las herramientas.
• La revisión humana pausa la ejecución para que una persona o una política pueda aprobar o rechazar una acción sensible.

Elige el control adecuado

Agrega una salvaguarda bloqueante

Usa salvaguardas de entrada cuando quieras realizar una validación rápida antes de iniciar la parte del flujo de trabajo que consume muchos recursos o produce efectos secundarios.

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())

Usa la ejecución bloqueante cuando iniciar el agente principal implique un costo o un riesgo demasiado alto. Usa salvaguardas en paralelo cuando reducir la latencia sea más importante que evitar trabajo especulativo.

Pausa la ejecución para la revisión humana

Las aprobaciones permiten incorporar la revisión humana a las llamadas a herramientas. El modelo puede decidir que hace falta una acción, pero la ejecución se pausa hasta que la apruebes o la rechaces.

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())

Este mismo patrón de interrupción se aplica incluso si la herramienta que requiere aprobación se encuentra en un nivel más profundo del flujo de trabajo, por ejemplo, después de una transferencia de control o dentro de una llamada anidada a agent.asTool().

Ciclo de vida de la aprobación

Cuando una llamada a una herramienta requiere revisión, el SDK sigue siempre la misma secuencia:

1. La ejecución registra una interrupción para solicitar aprobación en lugar de ejecutar la herramienta.
2. El resultado incluye interruptions y un state que permite reanudar la ejecución.
3. Tu aplicación aprueba o rechaza los elementos pendientes.
4. Reanudas la misma ejecución a partir de state en lugar de iniciar un nuevo turno de usuario.

Si la revisión puede tardar, serializa state, guárdalo y reanuda la ejecución más adelante. Sigue siendo la misma ejecución.

Alcance de los controles en el flujo de trabajo

Las salvaguardas a nivel de agente se aplican en puntos específicos:

• Las salvaguardas de entrada se ejecutan solo para el primer agente de la cadena.
• Las salvaguardas de salida se ejecutan solo para el agente que produce la salida final.
• Las salvaguardas de herramientas se ejecutan en las herramientas de función a las que están asociadas.

Si necesitas comprobar cada llamada a una herramienta personalizada en un flujo de trabajo coordinado por un agente, no dependas solo de las salvaguardas de entrada o de salida a nivel de agente. Coloca la validación junto a la herramienta que produce el efecto secundario.

Revisa las acciones de ciberseguridad antes de ejecutarlas

En los flujos de trabajo de ciberseguridad autorizados, evalúa cada llamada sensible a una herramienta antes de ejecutarla. Usa salvaguardas de herramientas e interrupciones para solicitar aprobación y hacer cumplir el alcance documentado de la intervención en el punto donde se producen los efectos secundarios:

1. Verifica que el objetivo y la acción propuestos, los argumentos de la herramienta, la identidad de quien realiza la llamada y el período de intervención se ajusten al alcance aprobado.
2. Proporciona a un componente de políticas independiente o a un revisor la acción exacta que se propone y únicamente el contexto necesario para evaluarla.
3. Deniega el acceso a hosts fuera del alcance aprobado y bloquea el robo de credenciales, la persistencia, la exfiltración de datos, los cambios destructivos, el acceso a producción y los intentos de eludir la política.
4. Pausa las acciones ambiguas o de alto riesgo para obtener la aprobación explícita de una persona antes de ejecutar la herramienta.
5. Aplica límites independientes para el sistema de archivos, la red, la identidad y el proyecto. Registra las decisiones y los resultados de la ejecución. Bloquea la acción si vence el plazo de revisión o si la revisión deja de estar disponible.

Las aplicaciones que usan la API de Responses o el SDK de agentes no heredan automáticamente la Revisión automática de Codex. Incorpora la revisión y los mecanismos para hacer cumplir la política en tu propio arnés de ejecución. La política de código abierto del revisor de Codex muestra una forma de hacerlo. Consulta Modelos y acceso de confianza para conocer las condiciones de acceso autorizado a los modelos y Configuración recomendada para configurar la intervención de forma segura.

La transmisión y la revisión diferida usan el mismo modelo de estado

La transmisión no crea un sistema de aprobación independiente. Si una ejecución en modo de transmisión se pausa, espera a que la pausa se haga efectiva, inspecciona interruptions, resuelve las solicitudes de aprobación y reanuda la ejecución a partir del mismo state. Si la revisión se realiza más adelante, guarda el estado serializado y continúa la misma ejecución cuando recibas la decisión.

Próximos pasos

Una vez que tengas claro dónde se aplica cada control, continúa con la guía sobre el entorno de ejecución o la interfaz de herramientas correspondiente.