Revisão automática

Enquanto o agente trabalha, a revisão automática aprova ou nega as solicitações de aprovação que ela pode avaliar, assim como o recurso de aprovação automática do ChatGPT e do Codex. Para configurá-la, use o campo review ao criar uma sessão para o agente. A configuração se aplica aos turnos raiz e a todos os subagentes criados por esses turnos.

Como funciona

Com a revisão automática, seus agentes podem usar o recurso “Aprovar por mim” do harness do Codex. Durante uma sessão, uma ação que o agente pretende executar pode gerar uma solicitação de aprovação se exigir permissões adicionais. Entre as ações que podem gerar essas solicitações estão:

• Comandos de shell e entradas de terminal que exigem aprovação, como comandos que solicitam elevação de privilégios ou que podem ser perigosos.
• Alterações em arquivos que exigem aprovação.
• Solicitações de permissões adicionais, como acesso mais amplo ao sistema de arquivos ou à rede.
• Solicitações de acesso à rede que exigem aprovação e estão sujeitas às restrições de rede do ambiente.
• Chamadas de ferramentas MCP cujas regras de aprovação exigem confirmação.

Um modelo revisor gerenciado pela OpenAI usa o contexto da conversa para avaliar o que a ação faria, quais riscos apresenta e se está de acordo com a intenção do usuário. Em seguida, o modelo aprova ou nega a solicitação.

A cobrança pelos tokens usados na revisão se soma à cobrança pelo uso do modelo do agente.

Seu aplicativo continua responsável pelas solicitações de acesso a origens no navegador e pelas solicitações de login. Os formulários MCP que exigem o preenchimento de dados e as solicitações que direcionam o usuário a uma URL seguem os fluxos existentes. A revisão automática dispensa a criação de novos manipuladores de eventos de aprovação. Consulte Eventos e itens para acompanhar o progresso do agente e verificar o resultado do turno.

Escolha um modo de revisão

Defina o campo review da sessão de acordo com o comportamento desejado:

Se você omitir review, a sessão usará o valor padrão "none". A configuração é mantida quando a sessão é retomada. Para alterá-la, envie "auto_review" ou "none". A API não aceita null. Definir review como "none" não encaminha essas ações ao seu aplicativo para aprovação manual.

Prepare o ambiente de execução

Para execução hospedada pela OpenAI, crie a sessão com um novo ambiente. Se preferir, crie o ambiente a partir de um modelo de ambiente. A revisão automática não está disponível quando você usa environment_id para reutilizar um ambiente hospedado existente.

Para execução em infraestrutura própria, siga as instruções de configuração do ambiente auto-hospedado e atenda aos pré-requisitos do sandbox para seu sistema operacional antes de ativar a revisão automática. Definir review, por si só, não configura o isolamento do ambiente.

A revisão automática preserva as restrições de rede do ambiente. Configure o acesso de saída nas configurações de rede do ambiente. Essas restrições se aplicam mesmo quando o acesso a uma origem é aprovado no navegador.

Crie uma sessão com revisão automática

Defina review como "auto_review" ao criar uma sessão. Neste exemplo, o agente recebe a instrução de executar npm install em /workspace.

Com a chave de API e o SDK configurados, use um agente existente e um modelo de ambiente que forneça o Node.js e um projeto que contenha o arquivo /workspace/package.json. Substitua os IDs de agente e de modelo do exemplo pelos seus.

1
2
3
4
5
6
7
8
9
10
11
12
13import OpenAI from "openai";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent_id: "agt_123",
  environment: {
    type: "openai_hosted",
    environment_template_id: "envtmpl_123",
  },
  review: "auto_review",
  input: "Run npm install in /workspace.",
});
console.log(session.id);

1
2
3
4
5
6
7
8
9
10
11
12
13from openai import OpenAI

client = OpenAI()
session = client.beta.agents.sessions.create(
    agent_id="agt_123",
    environment={
        "type": "openai_hosted",
        "environment_template_id": "envtmpl_123",
    },
    review="auto_review",
    input="Run npm install in /workspace.",
)
print(session.id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

client := openai.NewClient()
session, err := client.Beta.Agents.Sessions.New(context.Background(), openai.BetaAgentSessionNewParams{
	AgentID: openai.String("agt_123"),
	Environment: openai.EnvironmentParamUnion{
		OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{
			EnvironmentTemplateID: openai.String("envtmpl_123"),
		},
	},
	Review: openai.BetaAgentSessionNewParamsReviewAutoReview,
	Input:  openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Run npm install in /workspace.")},
})
if err != nil {
	panic(err)
}
fmt.Println(session.ID)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var session =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agentId("agt_123")
                .environment(
                    EnvironmentParam.OpenAIHosted.builder()
                        .environmentTemplateId("envtmpl_123")
                        .build())
                .review(SessionCreateParams.Review.AUTO_REVIEW)
                .input("Run npm install in /workspace.")
                .build());
System.out.println(session.id());

1
2
3
4
5
6
7
8
9
10
11
12
13require "openai"

client = OpenAI::Client.new
session = client.beta.agents.sessions.create(
  agent_id: "agt_123",
  environment: {
    type: :openai_hosted,
    environment_template_id: "envtmpl_123"
  },
  review: :auto_review,
  input: "Run npm install in /workspace."
)
puts session.id

1
2
3
4
5
6
7
8
9
10
11
12
13curl --fail-with-body https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_123",
    "environment": {
      "type": "openai_hosted",
      "environment_template_id": "envtmpl_123"
    },
    "review": "auto_review",
    "input": "Run npm install in /workspace."
  }'

Use o id da sessão retornado pela API para alterar o modo de revisão entre tarefas. Consulte a referência de criação de sessões para ver os campos da solicitação.

Seu projeto precisa ter acesso à revisão automática. Se o recurso estiver indisponível, a API rejeitará as solicitações para ativá-lo e indicará review como o parâmetro afetado.

Altere o modo de revisão

Atualize o campo review da sessão entre tarefas. Antes de alterar o modo, aguarde até que a tarefa principal esteja ociosa e não haja mais nenhum envio de dados de entrada em andamento. Este exemplo desativa a revisão automática. Substitua sess_123 pelo ID da sessão retornado no exemplo anterior:

const updatedSession = await client.beta.agents.sessions.update("sess_123", {
  review: "none",
});
console.log(updatedSession.id);

updated_session = client.beta.agents.sessions.update("sess_123", review="none")
print(updated_session.id)

updatedSession, err := client.Beta.Agents.Sessions.Update(context.Background(), "sess_123", openai.BetaAgentSessionUpdateParams{
	Review: openai.BetaAgentSessionUpdateParamsReviewNone,
})
if err != nil {
	panic(err)
}
fmt.Println(updatedSession.ID)

import com.openai.models.beta.agents.sessions.SessionUpdateParams;

var updatedSession =
    client
        .beta()
        .agents()
        .sessions()
        .update(
            SessionUpdateParams.builder()
                .sessionId("sess_123")
                .review(SessionUpdateParams.Review.NONE)
                .build());
System.out.println(updatedSession.id());

updated_session = client.beta.agents.sessions.update("sess_123", review: :none)
puts updated_session.id

curl --fail-with-body https://api.openai.com/v1/agents/sessions/sess_123 \
  -X POST \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "review": "none"
  }'

A API retorna 200 OK e a sessão atualizada. Omita review nas demais atualizações da sessão para manter o valor atual. Para reativar a revisão automática, envie "review": "auto_review". Consulte a referência de atualização de sessões para ver os campos da solicitação.

Se você solicitar uma alteração de modo enquanto a tarefa principal estiver ativa ou ainda houver um envio de dados de entrada em andamento, a API retornará 409 Conflict. Nesse caso, a API não aplicará nenhuma das atualizações da solicitação. Tente novamente quando a tarefa estiver ociosa e todos os envios de dados de entrada tiverem sido concluídos. Trate o código 409 mesmo depois de verificar o estado da sessão, pois novos dados de entrada podem chegar antes da atualização. Você pode enviar o valor atual do modo de revisão mesmo enquanto a tarefa estiver ativa.

Consulte uma sessão ou liste as sessões para verificar o valor salvo de review. Se a resposta omitir o campo, considere que o valor é "none".