Salvaguardas e revisão humana

Use salvaguardas para fazer verificações automáticas e recorra à revisão humana para decidir se uma ação deve ser aprovada. Juntas, elas definem quando a execução deve continuar, pausar ou parar.

• Salvaguardas validam automaticamente a entrada, a saída ou o comportamento das ferramentas.
• A revisão humana pausa a execução para que uma pessoa ou uma política possa aprovar ou rejeitar uma ação sensível.

Escolha o controle adequado

Adicione uma salvaguarda bloqueante

Use salvaguardas de entrada para fazer uma validação rápida antes de iniciar uma etapa do fluxo de trabalho que tenha custo elevado ou produza efeitos colaterais.

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

Use a execução bloqueante quando iniciar o agente principal tiver um custo ou risco muito alto. Execute as salvaguardas em paralelo quando reduzir a latência for mais importante do que evitar trabalho especulativo.

Pause para revisão humana

As aprovações permitem que uma pessoa revise as chamadas de ferramentas. O modelo ainda pode decidir que uma ação é necessária, mas a execução fica em pausa até que você aprove ou rejeite a ação.

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

Esse padrão de interrupção também se aplica quando a ferramenta que exige aprovação aparece em uma etapa posterior do fluxo de trabalho, por exemplo, após uma transferência de controle para outro agente ou dentro de uma chamada aninhada a agent.asTool().

Ciclo de aprovação

Sempre que uma chamada de ferramenta precisa de revisão, o SDK segue as mesmas etapas:

1. A execução registra uma interrupção para aprovação em vez de executar a ferramenta.
2. O resultado inclui interruptions e um state que permite retomar a execução.
3. Seu aplicativo aprova ou rejeita os itens pendentes.
4. Você retoma a mesma execução a partir de state em vez de iniciar um novo turno do usuário.

Se a revisão puder demorar, serialize state, armazene o estado e retome a execução mais tarde. A execução continua sendo a mesma.

Onde as salvaguardas se aplicam no fluxo de trabalho

As salvaguardas definidas no nível do agente atuam em pontos específicos:

• As salvaguardas de entrada são executadas apenas para o primeiro agente da cadeia.
• As salvaguardas de saída são executadas apenas para o agente que produz a saída final.
• As salvaguardas de ferramenta são executadas nas ferramentas de função às quais estão associadas.

Se você precisar verificar cada chamada de ferramenta personalizada em um fluxo de trabalho coordenado por um agente gerenciador, não dependa apenas das salvaguardas de entrada ou saída do agente. Faça a validação junto à ferramenta que produz o efeito colateral.

Revise as ações de cibersegurança antes da execução

Em fluxos de trabalho de cibersegurança autorizados, avalie cada chamada sensível de ferramenta antes de executá-la. Use salvaguardas de ferramenta e interrupções para aprovação para garantir o cumprimento do escopo definido por escrito para a operação no ponto em que ocorrem os efeitos colaterais:

1. Verifique se o alvo e a ação propostos, os argumentos da ferramenta, a identidade de quem faz a chamada e o período da operação estão de acordo com o escopo aprovado.
2. Forneça a um componente de política separado ou a um revisor a ação exata que foi proposta e apenas o contexto necessário para avaliá-la.
3. Bloqueie o acesso a hosts fora do escopo, o roubo de credenciais, a persistência, a exfiltração de dados, as alterações destrutivas, o acesso ao ambiente de produção e as tentativas de contornar a política.
4. Pause as ações ambíguas ou de alto risco e exija aprovação humana explícita antes de executar a ferramenta.
5. Aplique limites independentes para o sistema de arquivos, a rede, a identidade e o projeto. Registre as decisões e os resultados da execução. Bloqueie a ação se o prazo da revisão expirar ou se a revisão ficar indisponível.

Os aplicativos que usam a API Responses ou o SDK de Agentes não herdam automaticamente a Revisão automática do Codex. Adicione mecanismos de revisão e de aplicação das políticas ao seu próprio harness. A política de código aberto do revisor do Codex exemplifica uma abordagem. Consulte Modelos e acesso confiável para saber mais sobre o acesso autorizado aos modelos e Configuração recomendada para configurar a operação com segurança.

O streaming e a revisão posterior usam o mesmo modelo de estado

O streaming não cria um sistema de aprovação separado. Se uma execução em streaming pausar, aguarde até que a pausa se efetive, examine interruptions, aprove ou rejeite os itens pendentes e retome a execução a partir do mesmo state. Se a revisão ocorrer mais tarde, armazene o estado serializado e continue a mesma execução quando receber a decisão.

Próximos passos

Depois de identificar onde cada controle se aplica, consulte o guia que aborda o ambiente de execução ou as ferramentas envolvidas.