Controladores de navegador y escritorio

Un controlador convierte las llamadas a herramientas permitidas en acciones en un navegador o escritorio que controlas. Usa un controlador de navegador cuando tu aplicación pueda informar sobre el texto de la página, los controles y las pestañas. Usa un controlador de computadora cuando el modelo deba trabajar con capturas de pantalla y coordenadas. El SDK envía solicitudes y despacha llamadas. Tu aplicación se encarga de la sesión, los permisos y la liberación de recursos.

Configurar los controles comunes

Comienza con el ejemplo de navegador en Python o Node. Incluye un controlador completo, una política de confirmación y una ejecución de Responses con un límite de solicitudes. Mantén la sesión abierta hasta que termine la ejecución. Python también ofrece las clases síncronas BrowserToolset y ResponsesToolRunner para controladores síncronos.

Aprobar acciones y administrar la sesión

Crea los controladores y los callbacks de aprobación en código de confianza de la aplicación. Mantén la configuración ejecutable separada de los datos de página que no sean de confianza y devuelve los datos de la página mediante los campos declarados en el informe del controlador.

Si seleccionas un método del navegador que modifica el estado o lee datos de diagnóstico, debes proporcionar confirm. Solo el valor exacto true en Node o True en Python aprueba una acción. navigate y new_tab también requieren urlPolicy (Node) o url_policy (Python). Ambos callbacks reciben un objeto independiente que contiene member, los argumentos validados en arguments, el estado anterior en state y call_id. El callback de la política de URL también recibe la URL solicitada. Modificar ese objeto no cambia la acción validada.

confirm aprueba los argumentos ya fijados de la acción. Su campo state contiene una observación anterior y no bloquea el documento ni el control que tiene el foco. La página puede navegar a otro destino o cambiar el foco mientras una persona decide. Si el consentimiento se refiere a una página o un control específicos, el controlador debe verificar el destino original al ejecutar la acción. En ese flujo, deshabilita key y rechaza type si el destino es nulo, ya que ambos usan el foco actual. Vincula de la misma forma a su destino las demás acciones que dependan del estado actual del navegador.

Para pedir permiso antes de leer una página privada, incluye los miembros de lectura en confirmReads (Node) o confirm_reads (Python). El mismo callback confirm se ejecuta antes de que el controlador lea el estado o el contenido. Su contexto contiene phase: "before_read" y state: null en Node o None en Python. Maneja ese caso sin leer los metadatos de la página. Si se rechaza la lectura, no se devuelve contenido ni estado de la página. Si omites esta opción, las lecturas existentes conservan su comportamiento y las aprobaciones obligatorias de acciones siguen vigentes.

En las llamadas a la computadora, confirma todas las comprobaciones de seguridad pendientes antes de que el auxiliar ejecute cualquier acción. approveSafetyChecks en Node y approve_safety_checks en Python deben devolver exactamente el valor booleano verdadero. Si falta el callback o se deniega la aprobación, la ejecución se detiene. El callback opcional beforeAction o before_action comprueba cada acción inmediatamente antes de ejecutarla, incluida la captura de pantalla final. Si lo proporcionas, también debe aprobar cada acción de forma explícita. Ni una elección del modelo ni un mensaje de finalización pueden otorgar la aprobación. Consulta las pautas de seguridad para el uso de la computadora.

Node pasa { signal } como último argumento a ambos callbacks de aprobación de la computadora. Python proporciona el argumento de palabra clave opcional cancelled si el callback lo acepta. Los callbacks existentes con menos argumentos siguen siendo compatibles. Usa este contexto para cerrar una solicitud de aprobación pendiente cuando se detenga la ejecución. El auxiliar espera a que termine el callback antes de liberar la sesión.

La aprobación de una acción de la computadora abarca sus argumentos ya fijados. La pantalla y el foco pueden cambiar mientras una persona decide. Si el consentimiento debe aplicarse a un destino específico, el controlador debe vincular la acción a ese destino o rechazarla si cambia el estado. Ejecuta las acciones de la computadora en un entorno aislado con acceso limitado a la red.

Restringir las URL

Habilita navigate o new_tab solo cuando la tarea los necesite. Proporciona tanto confirm como urlPolicy en Node, o confirm y url_policy en Python. El callback de URL recibe (context, url), con un contexto de ejecución opcional en Node o el argumento de palabra clave cancelled en Python. Debe devolver exactamente el valor booleano verdadero para que el SDK continúe con confirm. Una pestaña nueva en blanco con una URL nula también requiere confirmación, aunque no tiene una URL que verificar.

Analiza la URL solicitada. Compara su protocolo, nombre de host y puerto con los destinos permitidos para la tarea. No te bases en el prefijo de una cadena: https://example.com.evil.test no debe aceptarse como https://example.com. Un controlador de navegador sin funciones de navegación no necesita un callback de URL. El ejemplo de navegador deja estos métodos deshabilitados.

Aplica también una política de red en el navegador o el entorno. El callback verifica la navegación solicitada, pero no puede restringir redirecciones, ventanas emergentes, scripts de la página ni recursos incrustados. Mantén una misma sesión aislada entre solicitudes y cierra los recursos que haya creado tu aplicación. Deja los recursos prestados a cargo de su propietario.

Examinar el uso y los tiempos

Con ResponsesToolRunner, pasa onDiagnostic en Node u on_diagnostic en Python a run. Por cada solicitud de Responses completada, el callback recibe un registro con api: "responses", stage: "request", reason: "completed" y usage. Los datos de uso incluyen input_tokens, output_tokens y total_tokens cuando la API los proporciona. De lo contrario, el valor es null en Node o None en Python. Para medir el uso de la ejecución, suma por separado cada campo de tokens de todas las solicitudes completadas. Si falta el uso de alguna solicitud, los totales están incompletos.

ComputerToolset.run no informa el uso por solicitud mediante su callback de diagnóstico. La respuesta devuelta puede contener datos de uso únicamente para la última solicitud. Usa ResponsesToolRunner con ComputerToolset cuando necesites datos de uso por solicitud.

Los registros de diagnóstico también indican la API, la etapa, el motivo, el ID de la llamada, el miembro y la duración medida. No contienen el error original, texto de la página, argumentos ni imágenes. Un fallo del observador no puede aprobar una acción ni cambiar su resultado. Si tu aplicación incluye datos privados en los ID de las llamadas o en los nombres de los miembros, exclúyelos de los registros públicos.

Usa un observador síncrono. El ejecutor no espera a que terminen las tareas de diagnóstico. Programa en tu aplicación cualquier operación de almacenamiento asíncrona.

Los tiempos de las etapas pueden superponerse en las ejecuciones anticipadas, porque el tiempo de recepción del flujo puede incluir el de las acciones. No los sumes para calcular la duración total de la ejecución.

Cerrar y cancelar operaciones

Si dos llamadas se superponen, el auxiliar rechaza la nueva con un error que indica que está ocupado. El ejecutor también rechaza una segunda ejecución activa en la misma instancia. Asigna un único propietario a cada sesión de navegador o escritorio.

Llama a close() del auxiliar para rechazar nuevas operaciones. Su status es closed cuando ya no hay llamadas activas, o draining cuando una llamada anterior todavía puede producir efectos. Si el estado es draining, espera a que termine la llamada de ejecución original antes de cerrar el controlador o transferir la sesión a otro propietario. El auxiliar no cierra tu navegador ni tu escritorio. Si llamas a close() desde un callback del controlador, no espera a que termine ese mismo callback.

Los métodos cooperativos de los controladores de Node y las funciones ordinarias pueden aceptar un segundo argumento de contexto con signal. Los métodos de Python pueden aceptar el argumento de palabra clave cancelled. Comprueba la cancelación durante las operaciones largas, incluidas la navegación y las capturas de pantalla. Los callbacks existentes de un solo argumento siguen siendo válidos, pero el SDK no puede obligarlos a detenerse ni deshacer un efecto.

Contrato del controlador de navegador

Implementa state() y únicamente las operaciones que quieras exponer. Los métodos de Node pueden devolver un valor o una promesa. Python ofrece clases síncronas y asíncronas por separado. Cada operación recibe un único objeto o diccionario con argumentos validados. Para los ID de pestaña y los destinos que admiten la ausencia de valor, usa explícitamente null en Node y None en Python.

Al crear el auxiliar, Python rechaza las incompatibilidades que puede detectar entre métodos síncronos y asíncronos. Usa métodos async def con AsyncBrowserToolset. Si envuelves los métodos, conserva los metadatos del decorador o las anotaciones de retorno. Los envoltorios opacos se comprueban al llamarlos. Los protocolos opcionales como BrowserReadDriver y AsyncBrowserReadDriver te permiten especificar los tipos de un controlador parcial sin implementar todas las operaciones. Node exporta BrowserArguments<Member> y BrowserResult<Member> para las entradas y salidas correspondientes.

state() devuelve tabs, un arreglo de objetos con id, title, url y active. Usa ID estables y marca la pestaña que realmente está activa. Excluye las credenciales y la información privada de los títulos y las URL. El SDK devuelve el estado actual después de las operaciones ordinarias, incluso si fallan. Si se rechaza una lectura protegida, se devuelve una respuesta de rechazo fija sin leer ni exponer el estado. Si falla una lectura de estado obligatoria, la ejecución se detiene. Los lectores de estado de Node reciben { signal }. Los de Python pueden aceptar el argumento de palabra clave cancelled. Usa este contexto para finalizar las lecturas de estado pendientes cuando quien hizo la llamada detenga la ejecución. Los lectores existentes sin argumentos siguen siendo compatibles.

El estado de las pestañas indica los orígenes HTTP y HTTPS, como https://example.com:8443, sin credenciales, rutas, consultas ni fragmentos. El formato de estado anterior, sin metadatos de observación, conserva about:blank y solo indica el esquema de las demás URL, como data: o file:. Su límite de 2048 bytes en UTF-8 se aplica al valor informado, por lo que una ruta de página larga no impide leer el estado. Si el estado incluye metadatos de observación V1, los títulos se recortan a un máximo de 1024 bytes en UTF-8 sin dividir caracteres y se establece title_truncated cuando corresponde. Debes seguir aplicando las reglas de privacidad de tu aplicación a los títulos y al contenido de la página.

Seleccionar métodos

De forma predeterminada, el SDK expone los siguientes 18 métodos cuando están implementados y deriva list_tabs de state(). No implementes list_tabs. Con una lista members, puedes exponer menos métodos o habilitar explícitamente los métodos de lectura por sección y de puntero o los métodos de diagnóstico, scripts y archivos. Los nombres deben ser únicos y corresponder a miembros predefinidos que implemente el controlador. Solo list_tabs funciona con state() sin necesidad de implementar otro método. Una lista vacía no expone ningún método. Al crear el auxiliar, el SDK copia la selección y conserva su propio orden de herramientas. Rechaza las llamadas deshabilitadas antes de leer el estado o solicitar consentimiento.

Para agregar un método opcional y conservar los métodos predeterminados implementados, usa additionalMembers en Node o additional_members en Python. No combines esta opción con members. El controlador debe implementar cada método que solicites agregar. BROWSER_MEMBERS y DEFAULT_BROWSER_MEMBERS enumeran los nombres predefinidos sin inspeccionar ningún controlador.

Deshabilitar list_tabs no oculta el estado que devuelven otras operaciones exitosas. En Python y Node, members filtra los métodos del auxiliar de navegador. Los nombres de funciones ordinarias pueden empezar con browser_, pero no deben coincidir con el nombre de una herramienta de navegador habilitada.

Salvo en switch_tab y close_tab, el argumento tab_id puede ser nulo. La dirección puede ser up, down, left o right. En Node, BrowserArguments<Member> describe cada objeto de argumentos. Python expone tipos de entrada con nombre, como TabInput, ReadPageInput y ClickInput.

Para que read_page, find y get_page_text proporcionen únicamente el estado actualizado del navegador, devuelve null o ningún valor en Node, o None en Python. Devuelve una cadena vacía cuando la lectura se complete sin texto.

En Node, todas las operaciones de esta tabla salvo list_tabs reciben { signal } como segundo argumento. list_tabs usa el lector de estado descrito anteriormente. Python pasa cancelled como argumento de palabra clave si el método lo acepta. Usa este contexto para detener operaciones pendientes, incluidas la navegación y la entrada de datos. Los métodos existentes de un solo argumento siguen siendo compatibles.

Para wait_for, usa texto no vacío de hasta 256 bytes en UTF-8 después de normalizar los espacios en blanco. El tiempo de espera debe ser de entre 1 y 30 000 milisegundos. Después de scroll_to, vuelve a leer la página actual antes de actuar sobre un control.

Devolver lecturas estructuradas

read_page, find y get_page_text pueden devolver BrowserReadV1, que incluye version: 1, el texto visible en text, un arreglo elements y un arreglo omitted. Cada elemento tiene una referencia ref única, una etiqueta label no vacía y uno de siete roles: button, textbox, combobox, checkbox, radio, slider o listbox.

Incluye el value de un campo o sus options (pares de label y value) solo si tu aplicación permite que el modelo los vea. Una casilla o un botón de opción puede indicar su estado con el booleano checked. Las opciones de listbox pueden incluir el booleano selected. El SDK omite estos campos para otros roles. Node omite los campos opcionales con valor undefined y rechaza los valores null en esos campos. get_page_text debe devolver un arreglo elements vacío. El SDK no convierte una cadena ordinaria en una lectura estructurada.

El SDK no limita la cantidad de elementos u opciones, el tamaño del texto de la página ni el tamaño total del informe. Las referencias y las etiquetas tienen un límite de 256 bytes, y los valores, de 512 bytes. Usa valores escalares Unicode válidos. Los controladores pueden indicar que la lectura es parcial mediante códigos únicos en omitted: report_limit, text_limit, target_limit, work_limit, frame_limit, unsupported_root, unsupported_control, remote_action, private, value o name_limit.

El controlador se encarga de determinar la visibilidad, proteger la privacidad de los campos y verificar la validez de las referencias. Después de la aprobación y antes de actuar, vuelve a comprobar la referencia en la página actual. La etiqueta de un control no otorga permiso para leer su valor. Limitar el tamaño no basta para garantizar la seguridad del contenido de la página.

Devolver imágenes del navegador

screenshot y zoom devuelven un input_image nativo con al menos un image_url o file_id no vacío. Pueden estar presentes ambos campos de origen. Cada origen no nulo debe ser una cadena no vacía. Los campos admitidos son type, image_url, file_id, detail y prompt_cache_breakpoint. El punto de interrupción de la caché debe ser { mode: "explicit" }. También se acepta un valor nulo si el tipo de contenido nativo lo permite. El SDK valida y copia estos campos antes de devolver la imagen. Ambos métodos de Node devuelven ResponseInputImageContent, donde detail puede omitirse o ser nulo. Si lo configuras, usa auto, low, high u original.

Para zoom, region es [left, top, right, bottom]. Las coordenadas deben ser enteros seguros no negativos y tanto el ancho como la altura deben ser positivos. El controlador se encarga de recortar la imagen y comprobar los límites. Todas las coordenadas posteriores siguen refiriéndose al área visible completa.

Habilitar los métodos de lectura por sección y de puntero

Estos seis métodos de navegador están deshabilitados de forma predeterminada, incluso en controladores que los implementan. Selecciónalos con members o agrégalos con additionalMembers en Node o additional_members en Python. Los 18 métodos predeterminados originales conservan sus nombres, argumentos y tipos de resultado. Si usas members, incluye los métodos predeterminados que aún necesites, como screenshot o read_page.

Node usa BrowserArguments<Member>. Python exporta ReadPageScopedInput, ClickAtInput, DragPathInput, HoldKeysInput, HoverAtInput y SetCheckedInput. Todos los campos son obligatorios. Para indicar la pestaña activa, tab_id puede ser null o None. Se rechazan los campos desconocidos, incluidos los campos adicionales de un punto de la trayectoria. Los números deben ser enteros seguros y finitos. Python rechaza True y False donde se requieren números.

click_at acepta coordenadas x e y no negativas, button con valor left, right o middle, y click_count con valor 1, 2 o 3. drag_path acepta entre 2 y 100 puntos con la estructura exacta {x, y} y coordenadas no negativas. Ambos métodos usan el área visible completa de la página en píxeles CSS, incluso después de aplicar zoom. El controlador debe comprobar los límites actuales. Sus campos keys contienen una lista de modificadores sin repeticiones: Control, Alt, Meta o Shift. La lista puede estar vacía.

hover_at mueve el puntero a las coordenadas CSS actuales sin mantener presionado ningún botón. set_checked establece el estado booleano solicitado en una casilla. Establecerlo en verdadero dos veces debe dejar la casilla marcada. Incluso si la operación no cambia nada, debe usar el destino original aún vigente y obtener confirmación. No debe aceptar un control obsoleto o reemplazado.

hold_keys acepta entre 1 y 8 nombres de teclas únicos y no vacíos, cada uno de hasta 64 bytes en UTF-8 y con valores escalares Unicode válidos. duration_ms debe estar entre 1 y 3000. Los métodos que cambian el estado requieren que confirm devuelva exactamente el valor booleano verdadero. Los métodos cooperativos reciben el contexto de cancelación de cada llamada. Node pasa { signal } como segundo argumento y Python pasa el argumento de palabra clave cancelled si el método lo acepta. Los métodos existentes de un solo argumento siguen siendo válidos.

Leer dentro de una sección

En read_page_scoped, un valor nulo de root permite descubrir las secciones visibles. Una raíz no nula debe ser una referencia de ámbito emitida por el controlador, no un selector. Debe contener al menos un carácter, usar Unicode válido y ocupar como máximo 256 bytes en UTF-8. Configura depth entre 1 y 32 y filter como all o interactive. La profundidad cuenta los niveles recorridos en el DOM dentro de esa raíz, independientemente de los límites para marcos o árboles de sombra.

Devuelve BrowserScopedReadV1, que amplía la lectura existente con scopes: [{ref, label}]. Cada referencia y cada etiqueta debe contener al menos un carácter, usar Unicode válido y ocupar como máximo 256 bytes en UTF-8. Las referencias de ámbito deben ser únicas y no deben coincidir con ninguna referencia de elemento. Este método rechaza las cadenas y los resultados nulos. El SDK copia los campos conocidos antes de solicitar el estado final.

Usa las referencias de ámbito únicamente para seleccionar otra raíz de lectura. Las operaciones que modifican elementos deben rechazarlas. Invalida las referencias de ámbito y de elemento en conjunto cuando cambien su pestaña, documento, generación o visibilidad. Conserva las reglas de privacidad de los campos y los límites existentes de trabajo total y de lectura.

Habilitar diagnósticos, scripts y transferencias de archivos

Estos cuatro métodos también están deshabilitados de forma predeterminada. Selecciona cada uno en members o agrégalo con additionalMembers o additional_members, y proporciona confirm, incluso para las lecturas de diagnóstico. Implementarlos en el controlador no basta para exponerlos al modelo.

Para read_diagnostics, elige console o network como origen y un límite entre 1 y 100. Devuelve una lectura estructurada con un arreglo elements vacío. En Node, usa el tipo de resultado BrowserTextReadV1. El controlador debe filtrar los datos privados y limitar el historial que conserva. No devuelvas encabezados sin procesar, cookies, credenciales ni mensajes de consola sin filtrar.

run_script acepta código fuente no vacío con Unicode válido y un tiempo de espera entre 1 y 30 000 milisegundos. El SDK conserva el código fuente completo. Devuelve texto con Unicode válido. Una cadena vacía es válida, pero un resultado nulo no lo es. El SDK conserva los resultados de gran tamaño. Los scripts se ejecutan con los privilegios de la página. Usa una sesión nueva sin credenciales, restringe su acceso a la red y deja de usarla si hay dudas sobre el estado de la ejecución. Que el proceso local deje de esperar no demuestra que el script de la página se haya detenido.

Los métodos de archivo solo aceptan un grant_id emitido por quien realiza la llamada. Debe contener al menos un carácter, usar Unicode válido y ocupar como máximo 256 bytes en UTF-8. La autorización identifica un único archivo aprobado para la tarea y no es una ruta ni una URL. El propietario del archivo debe obtener una aprobación independiente para ese archivo. Debe volver a verificar la vigencia y la titularidad, aplicar los límites de tamaño y permitir que la autorización se use una sola vez. La confirmación del navegador no sustituye la aprobación del archivo.

Devuelve exactamente version, status, effect y cleanup. Establece version en 1. cleanup puede ser not_started, pending o completed. Estas son las combinaciones válidas de estado y efecto:

El SDK copia y valida este resultado antes de solicitar el estado final del navegador. Solo completed establece ok en verdadero en la salida de la herramienta. En los demás casos se conserva el resultado estructurado con ok en falso, por lo que el ejecutor omite las llamadas de navegador dependientes en esa respuesta. Comprueba el estado real del archivo y de la aplicación antes de reintentar una transferencia cuyo resultado se desconozca. El resultado de una operación de archivo no demuestra que el posterior envío de un formulario o una operación de negocio se hayan completado correctamente.

run_script, upload_file y download_file reciben el contexto de cancelación de cada llamada. Node pasa { signal } como segundo argumento y Python pasa el argumento de palabra clave cancelled. Python exporta ReadDiagnosticsInput, RunScriptInput y BrowserFileInput.

Contrato del controlador de computadora

Un controlador de computadora recibe acciones nativas de la computadora y devuelve capturas de pantalla. Debe implementar los siguientes métodos. En Node, importa ComputerDriver desde openai. En Python, importa ComputerDriver o AsyncComputerDriver desde openai. Importa también el auxiliar correspondiente, ComputerToolset o, en Python, AsyncComputerToolset, desde openai.

Los métodos de acción reciben el objeto de acción de computadora ya generado, con sus campos en snake_case, y no devuelven ningún valor. Deben lanzar un error si no pueden ejecutar la acción. No ignores las entradas incompatibles sin informar del error. Node admite resultados síncronos o promesas. En Python, espera a que terminen los métodos asíncronos.

En Python, usa métodos síncronos con ComputerToolset y métodos async def con AsyncComputerToolset. Al crear el auxiliar, este rechaza las incompatibilidades que puede detectar. Al envolver los métodos, conserva los metadatos del decorador o las anotaciones de retorno. Los envoltorios opacos se comprueban al llamarlos, por lo que su propio código puede ejecutarse antes de que el auxiliar detecte una incompatibilidad.

En Node, usa ComputerCallInput para las llamadas que pases a ComputerToolset.execute(). Acepta llamadas nativas y llamadas modernas que incluyen un arreglo actions y omiten pending_safety_checks. Cuando se omite ese campo de forma válida, los callbacks de aprobación reciben una copia independiente de la llamada con una lista de comprobaciones vacía. Al volver a incluir la llamada, se conservan sus campos originales.

screenshot() devuelve un computer_screenshot con un image_url (que puede ser una URL de datos) o un file_id. Los auxiliares de computadora requieren al menos un origen de imagen y aceptan ambos campos de origen. El auxiliar no lee archivos locales. Las acciones se ejecutan una sola vez y en orden. Después, el auxiliar toma la captura de pantalla final. No reintenta las acciones del controlador.

Para un bucle de Responses que solo use la computadora, usa ComputerToolset.run o, en Python, AsyncComputerToolset.run. Usa un modelo disponible en tu proyecto que admita la herramienta de computadora. Para ejecuciones mixtas, pasa el auxiliar de computadora como opción computer del ejecutor de Responses. Node recibe los callbacks de computadora en la opción de ejecución computerOptions. Python recibe approve_safety_checks y before_action directamente como argumentos de palabra clave de la ejecución. El ejemplo de navegador solo controla un navegador. No implementa ni verifica un escritorio nativo.

Tanto el auxiliar de computadora como ResponsesToolRunner admiten la compactación de Responses mediante context_management. Verifican los campos obligatorios de cada elemento y vuelven a incluir el contenido cifrado sin cambios. Para ResponsesToolRunner, elige esta opción nativa o la opción local contextBudget o context_budget. No las combines.

Ejecutar una tarea con capturas de pantalla

Ejecutar tu primera tarea incluye un ejemplo completo en Python o Node. Usa la herramienta de computadora de Responses para mostrar los detalles de recolección en un navegador local.

Usar un escritorio aislado

Para controlar el escritorio de un sistema operativo, consulta el ejemplo completo de escritorio en Python o Node. Ambos usan un sistema Linux invitado y aislado. En las Mac con chip de Apple, el sistema Linux invitado se ejecuta en una máquina virtual. En Linux x86-64, se ejecuta en Docker. Cada ejemplo incluye un ejercicio local que no requiere una clave de API. La tarea en vivo verifica tanto el registro del navegador como el archivo guardado. Para configurar tu propio entorno, comienza con la receta de Docker y adapta el contrato del controlador descrito anteriormente.

Combinar acciones del navegador con otras herramientas

El ejecutor de Responses puede combinar los auxiliares de navegador y computadora con funciones ordinarias, búsqueda web, búsqueda de archivos, intérprete de código, generación de imágenes y herramientas MCP remotas. Los resultados de las herramientas del servidor conservan su contenido nativo y los ID de los contenedores cuando la siguiente solicitud vuelve a incluir la respuesta. Si los resultados del servidor indican un fallo, están incompletos o siguen pendientes, el turno se detiene antes de las acciones locales.

Cuando una ejecución declara herramientas del servidor, las llamadas locales esperan a que se complete la respuesta, incluso si eager está habilitado. El ejecutor debe examinar los resultados del servidor y las solicitudes de aprobación que lleguen después antes de poder actuar de forma segura.

Una vez completado el turno, supplyOutputs en Node o supply_outputs en Python puede sustituir el resultado de una función ordinaria que aún no se haya intentado ejecutar si su registro permite sustituciones. Esto también funciona sin una política explícita de ejecución anticipada. Una sustitución no puede responder a una llamada de navegador, una llamada de computadora ni una solicitud de aprobación de MCP.

Este ejecutor necesita respuestas almacenadas para continuar después de la generación de imágenes. Rechaza store: false en Node o store=False en Python cuando declaras image_generation. Habilita el almacenamiento cuando corresponda o usa client.responses.create para una única solicitud sin estado. El ejecutor nunca habilita el almacenamiento por ti.

Reutiliza las herramientas de función tipadas para evitar repetir su validación. En Node, envuelve una zodResponsesFunction o standardResponsesFunction con runnerFunction de openai/helpers/responses-tool-runner. La herramienta debe incluir su callback. En Python, usa RegisteredFunction.from_tool o AsyncRegisteredFunction.from_tool con una pydantic_responses_function_tool existente y un ejecutor tipado explícito. Los argumentos no válidos detienen la ejecución antes de que se invoque ese ejecutor. Una salida no válida del callback detiene la ejecución sin repetir el efecto. Los registros directos de RunnerFunction y RegisteredFunction conservan el comportamiento existente de sus argumentos.

Para MCP, proporciona approveMcp en Node o approve_mcp en Python. El callback recibe una copia independiente de la solicitud de aprobación real y devuelve verdadero o falso. El ejecutor vincula la respuesta al ID de esa solicitud y al servidor declarado. No puede inventar una aprobación ni interpretar un mensaje final como consentimiento.

Las solicitudes que declaran herramientas MCP deshabilitan los reintentos automáticos del SDK, con o sin registro persistente. Si una solicitud falla, verifica qué hizo el servidor MCP antes de iniciar otra ejecución.

Manejar fallos

Para un problema recuperable, como una referencia obsoleta, lanza BrowserError únicamente con texto que sea seguro mostrar al modelo. Otros errores que lance una operación del navegador generan un mensaje de fallo genérico. Ante estos fallos, el ejecutor proporciona una salida para cada llamada de navegador, omite las operaciones de navegador restantes de esa respuesta y permite que el modelo vuelva a elegir en el turno siguiente. Un resultado devuelto no válido o un estado no válido detienen la ejecución. También se detiene si no se puede informar el estado, falla una función ordinaria o no se aprueban las comprobaciones nativas de la computadora.

Configura maxSteps o max_steps para limitar la cantidad de solicitudes a la API. El valor predeterminado es 20. La última solicitud permitida no puede iniciar nuevos efectos. Un reintento HTTP del SDK no vuelve a ejecutar una acción del controlador. Usa signal en Node o cancelled en Python para detener la ejecución entre operaciones. No siempre es posible deshacer una llamada del controlador que ya está en curso.

ResponsesToolRunner conserva tool_choice en cada solicitud. Una selección que siempre exige una herramienta local impide que la ejecución termine, por lo que el ejecutor la rechaza antes de comenzar. Usa auto para un bucle o responses.create para una única solicitud con selección forzada. Las selecciones obligatorias que también permiten una herramienta del servidor declarada siguen siendo válidas.

Resolver problemas de una ejecución

Corregir clics fuera del destino

Toma una captura de pantalla nueva y comprueba que muestre la ventana deseada. Usa el mismo sistema de coordenadas para la captura y la acción. Si envías una captura de 800 × 600 de una pantalla de 1600 × 1200, multiplica por dos ambas coordenadas devueltas antes de hacer clic. Si un controlador de computadora envía una captura recortada, suma el desplazamiento del recorte después de ajustar la escala. Los métodos de puntero del controlador de navegador usan píxeles CSS del área visible completa de la página, incluso después de aplicar zoom. No los confundas con los píxeles de la pantalla.

El tamaño de la captura de pantalla afecta la cantidad de tokens de entrada y el costo. Consulta Tomar capturas de pantalla para conocer las dimensiones de imagen y los límites del modelo.

Transmitir y reanudar una ejecución

De forma predeterminada, las ejecuciones de Responses no usan transmisión en tiempo real. Con stream y onEvent (Node) u on_event (Python), el ejecutor proporciona copias independientes de los eventos del flujo y espera a que la respuesta termine antes de ejecutar acciones. Con eager, puede ejecutar por anticipado los elementos de salida completados, respetando su orden. Nunca ejecuta fragmentos incrementales de argumentos.

Habilita la ejecución anticipada solo si es seguro ejecutar un elemento completado antes de que el ejecutor valide toda la respuesta. Si un evento posterior modifica o elimina ese elemento, el ejecutor se detiene y conserva el registro de su ejecución. No puede deshacer la acción. Si todas las acciones deben esperar a que se valide la respuesta completa, deja deshabilitada la ejecución anticipada o usa una política vacía de ejecución anticipada.

Si los elementos completados llegan fuera de orden o hay saltos en sus índices, el ejecutor espera a recibir la respuesta completa antes de ejecutar esa parte de la secuencia. Si falla el flujo, los efectos ya completados siguen registrados.

Con earlyExecution o early_execution, puedes restringir la ejecución anticipada a los nombres de función seleccionados tal como se transmiten en el protocolo y controlar el despachador nativo de la computadora con un booleano independiente. Un objeto vacío pospone todas las herramientas locales. Si omites la opción, se conserva el comportamiento habitual de ejecución anticipada para todas las herramientas. La primera herramienta pospuesta también pospone todas las siguientes para preservar su orden. Con iterate(), examina el turno completado antes de avanzar. Si cierras la iteración en ese punto, no se ejecuta ninguna herramienta pospuesta. Estas opciones cambian el momento de ejecución, pero no la aprobación.

Para una llamada completada, beforeEarlyCall o before_early_call puede devolver defer antes del despacho. No puede adelantar una llamada que esté fuera de la lista permitida para ejecución anticipada. Marca una función ordinaria como independent: true solo cuando pueda ejecutarse sin depender de otras acciones. Sin un registro persistente, las funciones independientes pueden ejecutarse mientras avanza el flujo. Las ejecuciones persistentes, las acciones del navegador y las acciones de la computadora mantienen el orden. Las operaciones iniciadas conservan su registro de ejecución incluso si falla otra llamada.

De forma predeterminada, se ejecutan simultáneamente como máximo dos llamadas anticipadas independientes. Para cambiar ese límite, establece maxConcurrentCalls en Node o max_concurrent_calls en Python en un entero positivo. El ejecutor espera a que termine el grupo actual antes de leer más llamadas del flujo. Esta opción solo se aplica a ejecuciones anticipadas independientes sin registro persistente. Cada función debe limitar las operaciones que inicie por su cuenta.

Si se interrumpe una ejecución anticipada, revisa ResponsesToolRunnerError.attemptedCallIds y completedCallIds en Node, o attempted_call_ids y completed_call_ids en Python. Contienen los ID de las llamadas, sin resultados, argumentos ni mensajes del controlador. Es posible que ya se hayan producido efectos. Consulta la fuente de referencia del estado de la aplicación antes de reintentar una acción que ya se intentó o cuyo resultado es incierto.

Usa contextBudget o context_budget para limitar la cantidad de bytes e imágenes de entrada de la siguiente solicitud, con o sin almacenamiento persistente. La proyección conserva las observaciones actuales y las relaciones necesarias entre herramientas. Un límite en memoria no permite recuperar una ejecución después de que finalice el proceso.

Al terminar un turno, appendUserText o append_user_text pone en cola las indicaciones de una persona. El ejecutor las agrega después de registrar las salidas pendientes. El método acepta texto, no salidas arbitrarias de herramientas ni objetos de aprobación, y no restablece el límite de solicitudes.

Usa este método para precisar la tarea actual, por ejemplo, para pedirle al agente que verifique una fecha diferente. Si el usuario reemplaza la tarea, detén la ejecución actual y espera a que termine antes de iniciar otra. Vuelve a leer el estado de la aplicación y obtén una nueva aprobación para las acciones nuevas. Conserva el registro de la ejecución anterior. Cambiar las instrucciones no deshace sus efectos.

Para poder recuperar la ejecución, proporciona un ledger que guarde cada punto de control bajo el control exclusivo de un único propietario de la ejecución. Reanuda únicamente desde el final de un turno completado. Si una acción sigue pendiente o su resultado es incierto, primero debes conciliar su registro con lo que ocurrió. Al reanudar, se conservan la cantidad de solicitudes restantes y el historial completado. La compactación local según el límite de contexto conserva toda la evidencia en el registro persistente y mantiene fijas las observaciones actuales, las comprobaciones de seguridad, los mensajes y el razonamiento. Nunca otorga aprobación.

Cada operación de guardado recibe una copia independiente y completa del punto de control, incluso cuando se guarda antes y después de los efectos locales. El punto de control incluye el lote completo y el historial acumulado. En lotes grandes, el trabajo total de copiar y almacenar estos registros puede crecer de forma cuadrática. Elige un sistema de almacenamiento adecuado para ese volumen. contextBudget y context_budget limitan la entrada de las solicitudes, pero no el almacenamiento del registro persistente.

Si se interrumpe la ejecución con un punto de control pendiente, este contiene el último prefijo guardado. Puede omitir texto posterior y propuestas que aún no se intentaron ejecutar. Nunca autoriza la repetición de acciones. Antes y después de un efecto, el punto de control guardado incluye todo el prefijo observado y los registros de ejecución.

Una ejecución que incluye herramientas MCP guarda un punto de control pendiente antes de cada solicitud. Si falla la conexión, verifica qué hizo el servidor MCP antes de iniciar otra ejecución. No se puede reanudar automáticamente desde el punto de control pendiente.

Las declaraciones MCP guardadas omiten la autorización y los encabezados personalizados, y reemplazan las URL de los servidores por huellas SHA-256. Las solicitudes nativas siguen usando la URL original. Coloca las credenciales que deban rotarse en la autorización o en los encabezados. Cambiar la ruta de una URL o un valor de consulta no reconocido cambia su identidad y requiere una nueva ejecución. No se puede reanudar desde puntos de control que contengan URL de MCP sin procesar. Node requiere crypto.subtle.digest para guardar una URL de MCP. Las demás entradas y salidas de los puntos de control siguen siendo datos privados de la aplicación.

Al reanudar, proporciona credenciales vigentes y verifica que correspondan al servidor y a la cuenta previstos.

Las declaraciones guardadas del intérprete de código conservan los nombres y dominios de las credenciales, pero eliminan sus valores secretos. Al reanudar, proporciona los valores vigentes en la configuración de la herramienta. Para las aprobaciones de MCP, un filtro vacío always: {} o never: {} se aplica a todas las herramientas.

Proporciona approveMcp en Node o approve_mcp en Python cuando la entrada inicial o un registro persistente guardado contengan solicitudes MCP aprobadas. Antes de guardar por primera vez o de enviar la primera solicitud a la API, el ejecutor vuelve a pedir cada aprobación para la que no haya una llamada MCP correspondiente ya completada. Esto se aplica con o sin registro persistente o límite de contexto. Las llamadas completadas y los rechazos anteriores se conservan sin cambios. Si se necesita una nueva aprobación y falta el callback, la ejecución se detiene.

Comprobar un controlador personalizado de forma local

Antes de adaptar la demo de reservas o el ejemplo de escritorio aislado, ejecuta el ejercicio local correspondiente. Agrega comprobaciones del estado real de la página, de los efectos de las entradas y de la liberación de recursos de tu controlador. La validación del SDK no demuestra que el entorno haya realizado una acción correctamente.

Consulta Ejecutar tu primera tarea para ver un flujo de trabajo funcional con el SDK y las recetas de integración para configurar el entorno. Después de cualquier cambio, verifica el formulario guardado, el archivo u otro registro de la aplicación antes de informar que la operación se completó correctamente.