Revisión automática

Mientras el agente trabaja, la revisión automática aprueba o rechaza las solicitudes de aprobación que admite, de forma similar a la función de aprobación automática de ChatGPT y Codex. Configúrala con el campo review al crear una sesión para tu agente. La configuración se aplica a los turnos raíz y a todos los subagentes que se creen en esos turnos.

Cómo funciona

La revisión automática pone a disposición de tus agentes la función “Aprobar por mí” del arnés de ejecución de Codex. Durante una sesión, el agente puede solicitar aprobación si necesita permisos adicionales para realizar una acción. Estos son algunos casos en los que puede solicitarla:

• Comandos de shell y entradas de terminal que requieren aprobación, por ejemplo, para elevar privilegios o ejecutar comandos potencialmente peligrosos.
• Cambios en archivos que requieren aprobación.
• Solicitudes de permisos adicionales, por ejemplo, para ampliar el acceso al sistema de archivos o a la red.
• Solicitudes de acceso a la red que requieren aprobación y están sujetas a las restricciones de red del entorno.
• Llamadas a herramientas MCP cuyas reglas de aprobación exigen confirmación.

Un modelo de revisión administrado por OpenAI usa el contexto de la conversación para evaluar qué efectos tendría la acción, qué riesgos implica y si coincide con la intención del usuario. Luego, el modelo aprueba o rechaza la solicitud.

Los tokens que se usan en la revisión se facturan además de los que consume el modelo de tu agente.

Tu aplicación sigue gestionando las solicitudes de acceso a orígenes del navegador y las solicitudes de inicio de sesión. Los formularios MCP que requieren datos del usuario y las solicitudes que dirigen al usuario a una URL siguen sus flujos habituales. La revisión automática no requiere nuevos controladores de eventos de aprobación. Consulta Eventos y elementos para seguir el progreso del agente y comprobar el resultado del turno.

Elegir un modo de revisión

Configura el campo review de la sesión para elegir el comportamiento:

Si omites review, se usa el valor predeterminado "none". La configuración se conserva al reanudar la sesión. Para cambiarla, envía "auto_review" o "none". La API no acepta null. Si configuras review como "none", tu aplicación no recibe esas acciones para su aprobación manual.

Preparar el entorno de ejecución

Para ejecutar el agente en un entorno alojado por OpenAI, crea la sesión con un entorno nuevo. Si quieres, puedes crearlo a partir de una plantilla de entorno. La revisión automática no está disponible si reutilizas un entorno alojado existente mediante environment_id.

Si alojas el entorno de ejecución en tu propia infraestructura, sigue las instrucciones para configurar el entorno y asegúrate de cumplir los requisitos previos del sandbox para tu sistema operativo antes de activar la revisión automática. Para configurar el sandbox en tu entorno, no basta con establecer el valor de review.

La revisión automática no modifica las restricciones de red del entorno. Configura el acceso de salida en la configuración de red del entorno. Estas restricciones siguen vigentes aunque se apruebe el acceso a un origen en el navegador.

Crear una sesión con revisión automática

Asigna a review el valor "auto_review" al crear una sesión. En este ejemplo se le pide al agente que ejecute npm install en /workspace.

Una vez que hayas configurado tu clave de API y el SDK, usa un agente existente y una plantilla de entorno que incluya Node.js y un proyecto que contenga /workspace/package.json. Reemplaza los identificadores del agente y de la plantilla del ejemplo por los tuyos.

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."
  }'

Usa el id de sesión que devuelve la API para cambiar el modo de revisión entre tareas. Consulta los campos de la solicitud en la referencia para crear una sesión.

Tu proyecto debe tener acceso a la revisión automática. Si la función no está disponible, la API rechaza las solicitudes para activarla e indica que review es el parámetro afectado.

Cambiar el modo de revisión

Actualiza el campo review de la sesión entre tareas. Antes de cambiar el modo, espera a que la tarea principal esté inactiva y a que termine cualquier envío de datos de entrada en curso. En este ejemplo se desactiva la revisión automática. Reemplaza sess_123 por el identificador de sesión que obtuviste en el paso 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"
  }'

La actualización devuelve 200 OK y la sesión actualizada. Omite review en las demás actualizaciones de la sesión para conservar su valor. Para volver a activar la revisión automática, envía "review": "auto_review". Consulta los campos de la solicitud en la referencia para actualizar una sesión.

Si solicitas un cambio de modo mientras la tarea principal está activa o hay un envío de datos de entrada en curso, la API devuelve 409 Conflict. No se aplica ninguna de las actualizaciones incluidas en esa solicitud. Vuelve a intentarlo cuando la tarea esté inactiva y haya terminado el envío de datos de entrada. Maneja el error 409 incluso si ya comprobaste el estado de la sesión, porque pueden llegar nuevos datos de entrada antes de la actualización. Puedes enviar el valor actual del modo de revisión incluso mientras la tarea está activa.

Obtén una sesión o consulta la lista de sesiones para comprobar el valor guardado de review. Si la respuesta omite el campo, interpreta su valor como "none".