Jev Ultrafast: espacio de acciones con índice dinámico, dos decisiones en un solo recorrido
El protagonista de Manual avanzado, Jev Ultrafast, es un agent de navegador de código abierto de Browser Use × TypeSafe (github.com/browser-use/jev-ultrafast): dale un objetivo en lenguaje natural, Jev se encarga de elegir las operaciones y los elementos de la página, y un LLM pequeño solo escribe cadenas cuando hay que teclear——la búsqueda en Google Flights de Zúrich a Londres se completa en 7.1 segundos (los detalles de la medición están en la lección interpretación del rendimiento).
¿Por qué es tan rápido? La respuesta no está en un modelo de caja negra, sino en la combinación de tres cosas: espacio de acciones con índice dinámico, doble decisión en un solo recorrido, bucle ligero sin capturas de pantalla. Esta lección las desmonta——todo el agent son solo seis archivos fuente, y oficialmente se describe a sí mismo como «lo bastante pequeño para leerlo entero» (Small enough to read).
Qué podrás hacer al terminar
- Explicar el «espacio de acciones con índice dinámico»: cada observación genera una nueva tabla de elementos numerados, y los 8 tipos de operación solo ofrecen objetivos compatibles
- Leer la estructura de una solicitud de TypeSafe: pregunta de operation + target heads, dos decisiones comparten un solo recorrido de red
- Recorrer el bucle del agent con el código fuente a mano: sin capturas, una instantánea por llamada al navegador, validación antes del clic
- Enumerar los límites de seguridad: la salida del modelo nunca toca directamente el navegador, DONE requiere verificación independiente, y una lista de elementos no soportados como el shadow DOM
- Distinguir la versión local de código abierto del servicio en la nube BU Ultrafast de Browser Use Cloud
Tu situación actual
- Has usado agents de navegador que alimentan capturas a modelos multimodales: cada paso requiere capturas, lento y caro, y cualquier salto de animación de la página hace perder de vista los botones
- Has escrito scripts de automatización para sitios: un cambio de versión invalida todos los selectores, y mantenerlos es como perseguir un tren que ya arrancó
- Has oído que Jev Ultrafast busca vuelos en 7 segundos, pero no conoces los principios y, si no arranca, no sabes por dónde empezar a investigar
Cuándo usar esta técnica
Cuando necesitas:
- Entender primero los principios de este agent de navegador antes de instalarlo (próxima lección), y saber en qué archivo mirar cuando algo falla
- Evaluar si tu página web es adecuada: hay que ver primero con claridad límites como el shadow DOM, el canvas y las subidas de archivos
- Tomar prestado su enfoque para llevar el fan-out especulativo de Jev preguntas paralelas a un agent real
Y cuando no quieres:
- Copiar comandos a ciegas para ejecutar el demo y quedarte atascado al primer error
- Tratarlo como automatización universal: que dos sitios pasen ≠ fiabilidad amplia, y las palabras oficiales son igual de prudentes
🎒 Preparativos antes de empezar
- Has completado el Manual avanzado: sabes que Jev Ultrafast es el protagonista de esta etapa y que las próximas lecciones giran en torno a él
- Recuerdas el tipo de pregunta Choice: cada punto de decisión de Ultrafast es un Choice, y las respuestas incluyen probabilities y confidence
- (Opcional) abre github.com/browser-use/jev-ultrafast en el navegador; el texto citará nombres de archivos bajo
jev_ultrafast/, y leer en paralelo lo hace más claro
Esta lección solo cubre los principios y no requiere instalar nada——la parte práctica empieza en la próxima lección instalación y ejecución.
Idea central
El funcionamiento completo de Jev Ultrafast se puede comprimir en una frase (el sentido del texto original del README):
Dale un objetivo. Jev elige las operaciones y los elementos. El LLM pequeño solo escribe cadenas cuando la operación es
TYPE_TEXT.
Tres conceptos clave, que se desarrollan paso a paso en el «hazlo conmigo»:
| Concepto | Explicación en una frase | Fuente |
|---|---|---|
| Espacio de acciones con índice dinámico (action space) | Cada observación genera una nueva tabla de elementos numerados; el conjunto de operaciones es fijo en 8 tipos; cada operación solo ofrece objetivos soportados | README.md |
| Doble decisión en un solo recorrido | Una solicitud de TypeSafe pregunta a la vez «qué operación hacer» y «en qué elemento hacer clic para cada operación»; al ejecutar solo se usa la respuesta de objetivo que coincide | README.md, docs/design.md |
| Bucle sin capturas | El bucle del agent por defecto no consume capturas; Jev consume un state estructurado; las capturas son solo para el inspector | README.md |
Diferencias frente a los agents de navegador habituales basados en capturas (cada punto de la columna derecha se basa en la sección «Why it moves» del README):
| Dimensión | Agent basado en capturas | Jev Ultrafast |
|---|---|---|
| Entrada del modelo | Captura por página + DOM misceláneo | Tabla de elementos estructurada + texto visible, sin capturas |
| Coste de decisión | Varias llamadas al modelo por paso | Exactamente una solicitud de TypeSafe por ciclo de decisión |
| Adaptación a sitios | selectores/cadenas de campos preescritos, frágiles | la estrategia no contiene ningún script de sitio ni cadenas de campos prefabricadas |
| Generación de texto | el modelo grande genera todo el proceso, incluido el razonamiento | solo cuando TYPE_TEXT un LLM pequeño genera un fragmento de JSON |
💡 Versión de código abierto y el servicio en la nube BU Ultrafast
Browser Use Cloud ofrece una versión alojada BU Ultrafast, disponible en todos los planes: basta con configurar model: "bu-ultrafast" (cloud.browser-use.com). Esta versión de código abierto de GitHub se ejecuta en local. Este curso analiza la versión de código abierto.
Sígueme paso a paso
Paso 1: desmontar el espacio de acciones——la «lista de ingredientes» del principio de Jev Ultrafast
Por qué: todas las decisiones de Ultrafast se apoyan en el espacio de acciones. Si no entiendes de dónde sale la tabla de elementos, la estructura de la petición que viene después será solo memorizar JSON.
En cada observación de la página, el script de snapshot genera una nueva tabla de elementos numerada (texto original del ejemplo del README):
[1] button Change ticket type · Round trip
[2] combobox Where from? · San Francisco
[3] combobox Where to? · empty
[4] textbox Departure · empty
...Cada fila = número + role + nombre legible + valor actual. El número pertenece a esta tabla: cada observación genera una tabla de elementos nueva (README: Every observation produces a new element table). Un mismo nodo del DOM, aunque sea clicable y editable a la vez, solo ocupa un número (design.md: One node receives one index).
El conjunto de operaciones es fijo: 8 tipos (texto original del README):
| Operación | Uso |
|---|---|
CLICK | Clic en elementos, botones, elementos de menú, sugerencias de autocompletado, fechas de calendario |
TYPE_TEXT | Introducir/reemplazar texto en campos editables, el valor lo genera un LLM pequeño a partir del objetivo |
SELECT | Seleccionar un valor nativo de dropdown observado |
SCROLL_UP / SCROLL_DOWN | Desplazamiento de página (el snapshot lo añade automáticamente cuando hay dirección desplazable) |
WAIT | Esperar a que la página se actualice (100ms) |
DONE | Todos los requisitos se cumplen de forma visible |
BLOCKED | Ninguna operación soportada puede avanzar hacia el objetivo |
Dos detalles:
- Los objetivos solo contienen elementos compatibles. Cada operación tiene su propia tabla de objetivos candidatos, por lo que no aparecen errores de combinación como «escribir dentro de un botón».
- Los dropdowns nativos llevan un índice de dos niveles. El objetivo de SELECT no es el campo, sino «campo:número de opción»; por ejemplo,
2:3significa la opción número 3 del dropdown número 2——el número de opción lo posee el código, no lo inventa el modelo.
Deberías ver: la sección The action space del README muestra la misma tabla de elementos y el mismo conjunto de 8 nombres de operaciones, palabra por palabra.
- Puedo nombrar las 8 operaciones completas y explicar por qué el objetivo de SELECT lleva una numeración de dos niveles
Paso 2: leer una petición——la pregunta operation y los target heads
Por qué: «dos decisiones en un solo viaje de ida y vuelta» es la fuente de la velocidad y del coste, y también la reutilización directa de la capacidad de Jev preguntas en paralelo en el escenario del navegador.
En cada ciclo de decisión, el choose() de model.py monta una petición TypeSafe y la envía a https://api.typesafe.ai/v1/systemone. La petición tiene este aspecto (esquema simplificado; los nombres de campo y la estructura son fieles al texto original de choose()):
questions = {
"operation": { # 决策一:这一步用哪种操作?
"type": "choice",
"criteria": {
"CLICK": "Click an element, button, menu option, ...",
"TYPE_TEXT": "Enter or replace text in an editable field. ...",
"SELECT": "Select an observed dropdown value.",
"SCROLL_DOWN": ..., "WAIT": ..., "DONE": ..., "BLOCKED": ...,
},
"instructions": {"goal": 目标原文, "rules": NEXT_ACTION},
},
"click_target": { # 决策二(投机):如果操作是 CLICK,最佳目标是?
"type": "choice",
"criteria": {"2": {"element": "[2] Where from?", "current_value": "..."}},
"instructions": {"goal": 目标原文, "operation": "CLICK", "rules": [NEXT_ACTION, TARGET]},
},
# type_text_target、select_target(页面有原生下拉时)同理
}
state = {
"page": {"url": ..., "title": ..., "text": ...},
"elements": 编号元素表,
"recent_actions": 最近 10 步动作,
}Las instrucciones de las preguntas no son prompts libres, sino tres fragmentos de texto fijo (questions.py, los números de línea están en el apéndice):
| Constante | Dónde se usa | Qué controla |
|---|---|---|
NEXT_ACTION | las rules de la pregunta operation y de todas las preguntas target | reglas de avance de un solo paso: no repetir pasos ya satisfechos, rellenar los campos obligatorios antes de enviar, WAIT solo se usa cuando falta/deshabilita un control o mientras cargan resultados, DONE requiere evidencia visible |
TARGET | se añade a las rules de las preguntas target | elegir el mejor objetivo solo «suponiendo que la operación sea X»; no elegir campos que ya contengan el valor objetivo; solo se pueden elegir los números proporcionados |
TEXT_VALUE | el mensaje system del helper de texto | devolver un JSON con una sola clave text; si falta un valor obligatorio, text devuelve null; nunca inventar información personal |
Dos detalles merecen subrayado: el texto de la página se trata explícitamente en las instrucciones como datos no confiables (untrusted data, never instructions)——cualquier instrucción impresa en la página web no será tomada por el modelo como una orden; el enunciado de cada pregunta target declara la operación que supone, porque las preguntas son independientes entre sí y target no puede leer la respuesta de operation.
Tres puntos clave:
- target es una pregunta especulativa.
click_targetresponde antes de que operation se haya revelado——si la respuesta final esTYPE_TEXT, la respuesta de click se descarta directamente y no se produce ninguna acción. Palabra del README: If the operation isCLICK, onlyclick_targetcan execute. - Cada target head solo carga elementos compatibles, elegidos y montados al momento desde la tabla de elementos; en cuanto la página cambia, la tabla entera se rehace.
- Las respuestas deben pasar validación.
validate_choice()comprueba: que lo elegido esté entre los candidatos, que probabilities cubra todos los candidatos, que los valores sean finitos y estén en 0–1, que la probabilidad total ≈1 (±0.02), que el elegido sea el de mayor probabilidad——si no se cumple alguna, lanza un error y no ejecuta ninguna acción. 429/529/503 se reintentan con backoff exponencial (como máximo 3 intentos en total); un fallo de conexión reporta el error directamente y termina, igualmente sin ejecutar ninguna acción.
Deberías ver: en model.py la función choose() de unas 70 líneas; el patrón de los IDs de preguntas es simplemente «operation + cada nombre de operación en minúsculas + _target»; encajándolo podrás leer cualquier registro de peticiones.
- Puedo decir qué pregunta es especulativa y cuándo se descarta su respuesta
Paso 3: recorrer el bucle del agent——predecir, ejecutar, observar de nuevo
Por qué: tras saber «qué se pregunta», hay que saber «qué ocurre antes y después de la ejecución»——todo este nivel lo custodia código, sin gastar dinero del modelo.
El Agent.command() de agent.py es un bucle de tres estados:
ready ──predict──► predicted ──act──► ready ──…(循环直到 done / blocked)En cada tick se hace una pasada de predict → act (si la página cambió y caducó, se observa de nuevo y se repite la ronda). El diseño oficial de la capa de ejecución (cada punto del README Why it moves, traducción libre al español):
| Diseño | Función |
|---|---|
| El bucle por defecto no usa capturas de pantalla | Jev consume state estructurado; las capturas solo van al inspector |
| Una instantánea, una llamada al navegador | Controles visibles, nombres, valores y texto se leen de una sola vez, conservando referencias reales a nodos del DOM |
| Validación antes de clic/selección | Se contrasta contra document, el formulario, el elemento objetivo y el contexto cercano; la geometría se vuelve a analizar antes de la entrada y los controles ocultos se rechazan directamente |
| Tras escribir en un combobox, espera las sugerencias | Espera hasta que aparezcan sugerencias visibles, con un límite de 200ms; otras interacciones esperan como máximo dos fotogramas de animación o 50ms |
| Las pestañas en segundo plano mantienen el renderizado | Usa simulación de foco para evitar la limitación de animaciones, sin cambiar la pestaña visible de Chrome |
| Solo se envía el texto visible | El cuerpo y el pie de página fuera de pantalla no entran en el contexto del modelo (truncado a 6000 caracteres) |
| Reutilización de solicitudes de texto interrumpidas | Al reintentar con página caducada, solo se reutiliza si la entrada completa del helper de texto no ha cambiado ni un carácter |
Tres compuertas que aseguran contra desvíos (fuente original agent.py / design.md):
- Presupuesto por ejecución: 60 acciones de navegador, 120 solicitudes de decisión; la tabla de elementos conserva como máximo 250 candidatos, y los truncados no pueden volver a seleccionarse
- 3 acciones consecutivas sin ningún cambio en la página (y ninguna es WAIT) → el estado se pone en
blockedparada - Cada decisión se consume una sola vez antes de ejecutarse: un reintento jamás hará doble clic en el mismo botón; primero se registra la ejecución en el log, luego se observa la siguiente pantalla, y una observación caducada no borra la acción ya ejecutada
Deberías ver: dentro de agent.py en command() los tres segmentos tick / predict / act; la condición de disparo de blocked es que los últimos tres pasos page_changed sean todos False.
- Puedo emparejar los números de las tres compuertas: 60 / 120 / 250 y 3 cambios nulos consecutivos
Paso 4: recuerda el límite de seguridad: no manda lo que dice el modelo, manda el código
Por qué: en este tipo de agente a nivel de página, la mayor trampa no es la lentitud, sino «el modelo dirige el navegador para ejecutar directamente la salida del modelo». El diseño de Ultrafast bloquea ese camino en cada capa.
Cláusulas de límite (README Evidence and limits + design.md):
- La salida del modelo nunca se convierte en selector, coordenadas, comandos shell ni JS ejecutable: cada objetivo de ejecución se resuelve a partir de nodos DOM reales observados y numerados por código
- La salida del helper de texto debe parsearse como un pequeño JSON antes de escribirse: debe tener una sola clave
text, cadena no vacía, longitud ≤2000 (el original establece que en caso contrario no se escribe en ningún caso) - DONE no es prueba de éxito, requiere una verificación independiente del resultado: el ejemplo Flights lleva su propio
verify()para hacer 7 comprobaciones independientes (se explica en detalle en la lección ejecutar Google Flights) - El lector de DOM solo admite controles HTML y ARIA comunes; no implementa el algoritmo completo de accessible-name; shadow roots, frames, canvas, subidas de archivos, pestañas emergentes, scroll anidado y componentes de teclado arbitrariosno están soportados
- Más allá del modelo
DONE, la validez también se puede juzgar mal: una operación válida puede seguir siendo incorrecta. En las 6 alternancias de contraste oficiales, cada lado pasó 3/3; la conclusión de aceleración se basa en una muestra demasiado pequeña (3 más rápido en todos los casos, prueba de signos bilateral p=0.25), y el propio equipo oficial indica que es una muestra pequeña controlada sobre una configuración de tarea única y navegador único, no un criterio de fiabilidad general
Deberías ver: la sección Evidence and limits del README enumera el mismo conjunto de términos de límite (shadow roots, frames, canvas, etc.), en correspondencia uno a uno con la lista anterior.
- Puedo recitar los «dos no»: el modelo no ejecuta directamente, DONE no cuenta como prueba de éxito
Punto de control ✅
- Puedo escribir los 8 nombres de operaciones y explicar la regla de que cada operación solo admite objetivos compatibles
- Puedo explicar, en «una ida y vuelta con doble decisión», qué decisión es especulativa y cuál puede convertirse en acción
- Puedo emparejar los números de presupuesto y truncamiento: 60 acciones / 120 decisiones / 250 candidatos, 3 cambios nulos consecutivos → blocked
- Sé que la salida del modelo nunca se convierte en código ejecutable y que el texto debe parsearse como un JSON que solo contenga la clave text
- Distingo la diferencia entre la versión local de código abierto y la versión de servicio en la nube (
model: "bu-ultrafast")
Aviso de trampas
❌ Creer que toma capturas de pantalla en cada paso
El bucle del agente por defecto claramente no usa capturas de pantalla: Jev consume estado estructurado (tabla de elementos + texto visible). Las capturas las activan de forma explícita el inspector y la función de grabación (screenshots=True o record_dir=...).
Comprensión correcta: para ver con tus propios ojos qué está haciendo, usa el inspector del demo; el agente en sí no tiene dependencia visual, y esa es una de las razones de su velocidad.
❌ Tomar Ultrafast como automatización universal del navegador
Canvas, subida de archivos, interior de shadow DOM, nuevas pestañas emergentes, scroll anidado, componentes de teclado arbitrarios: el MVP no soporta ninguno. Solo reconoce controles HTML/ARIA comunes.
Manera correcta: antes de empezar una tarea, criba la página contra la lista de límites del paso 4; con páginas que involucren esos controles, por ahora no fuerces el paso; para el diagnóstico concreto, consulta resolución de problemas de Ultrafast.
❌ Querer escribir un script dedicado para un sitio concreto e insertar valores de campos preelaborados
En esta estrategia no hay scripts de acciones específicos por sitio, ni existen cadenas de campos preelaboradas: los cinco pasos de preparación manual de la versión prototipo fueron eliminados explícitamente por el equipo oficial en la revisión (design.md, «What changed after the first demo»).
Uso correcto: entrega el objetivo en una frase al Agent y deja que encuentre el camino por sí solo desde la tabla de elementos. Para personalizar tareas, usa la interfaz estándar de biblioteca de Agent, en lugar de inyectar lógica en la estrategia.
❌ Dar DONE por éxito
DONE es solo el juicio del modelo, no una prueba independiente. Incluso el ejemplo oficial de Flights debe completar su propio verify() para considerarse superado.
Manera correcta: define el éxito de la tarea como un paso de verificación independiente en el código, no como un bit de estado autoinformado por el modelo.
Técnicas avanzadas (opcional)
Lee una vez la sección «Qué cambió tras la primera demo» de design.md. Esa sección registra la evolución desde cinco pasos preconstruidos manuales hacia una estrategia dinámica, y también corrige la falsa identificación de checkboxes causada por «tratar todos los INPUT como editables»; al entender estos dos puntos, entenderás por qué existen los dos principios de diseño «sin cadenas preconstruidas» y «las reglas de editabilidad determinan la disponibilidad de TYPE_TEXT».
Cuando la próxima lección esté instalada, recórrela paso a paso con el inspector. Choose next se pausa antes de ejecutar, y el panel muestra los elementos numerados, la probabilidad de la operación, la probabilidad del objetivo y las acciones ya ejecutadas; comprobar con tus propios ojos los heads especulativos explicados en el paso 2 queda más grabado que leer el código diez veces.
Resumen de esta lección
✅ El principio de Jev Ultrafast = indexar dinámicamente el espacio de acciones (en cada observación, una nueva tabla de elementos numerados, 8 tipos de operaciones, y a cada operación solo se le asignan objetivos compatibles) + doble decisión en un solo recorrido (operation y cada target head en la misma petición; si el head especulativo no se usa, se descarta) + bucle ligero sin capturas de pantalla.
✅ Los tres conceptos clave provienen del texto original del README / design.md (The action space, Why it moves, Evidence and limits), y los seis archivos de código fuente son lo bastante pequeños para leerlos completos.
✅ La capa de ejecución no tiene inteligencia: hay validación antes de hacer clic, la salida del modelo no se ejecuta directamente, el texto debe pasar por un análisis JSON, y DONE requiere verificación independiente.
✅ Límites claros: 60 acciones / 120 decisiones / 250 candidatos; shadow DOM, canvas y subidas de archivos no son compatibles; los 6 ensayos comparativos son una muestra pequeña (la conclusión de aceleración tiene p=0.25), y los propios autores lo marcan como «no es una referencia general».
✅ Ejecuta localmente la versión de código abierto, y el navegador usa el servicio en la nube de BU Ultrafast (model: "bu-ultrafast").
Repaso de los campos de configuración clave (en la próxima lección se configuran a mano en .env; los valores de ejemplo provienen de .env.example):
| Campo | Valor de ejemplo | Descripción |
|---|---|---|
TYPESAFE_API_KEY | (obligatorio) | La llave para llamar a api.typesafe.ai/v1/systemone |
TYPESAFE_MODEL | jev-latest | TypeSafe Modelo de decisión; el valor por defecto ya es la última versión |
TEXT_MODEL_API_KEY | (TYPE_TEXT obligatorio) | La key del LLM pequeño, con interfaz compatible con OpenAI |
TEXT_MODEL_BASE_URL | https://openrouter.ai/api/v1 | El punto de conexión del helper de texto |
TEXT_MODEL | inception/mercury-2.5 | Modelo de texto ligero; se recomienda desactivar el razonamiento |
TEXT_MODEL_REASONING | none | Desactiva el razonamiento del modelo de texto |
Avance de la próxima lección
Con los principios claros, en la próxima lección Instalación y ejecución de Ultrafast: uv sync más dos API Key lo pondrás en marcha. Aprenderás:
- Desde git clone hasta uv run jev, cinco comandos para arrancar la demo local
- Qué gestiona cada variable de entorno en
.env, cuáles son obligatorias y cómo cambiar el modelo de texto a DeepSeek/GLM - Abre el inspector de 127.0.0.1:8766 y ve con tus propios ojos los elementos numerados y las probabilidades
- Cómo usar
browser-harness --doctory qué permitir cuando Chrome avise sobre la depuración remota
Apéndice: referencia del código fuente
Haz clic para expandir y ver las ubicaciones en el código fuente
Fecha de actualización: 2026-11-04 (repositorio github.com/browser-use/jev-ultrafast, fuente de información local sources/jev/repo-ultrafast/)
| Función | Ruta del archivo | Ubicaciones clave |
|---|---|---|
| Bucle completo y traspaso al helper de texto | jev_ultrafast/agent.py | L12 Agent clase; L52 command() (tick/predict/act); L163 run() |
| Construcción del espacio de acciones, petición a TypeSafe, generación de texto | jev_ultrafast/model.py | L48 action_space(); L81 choose(); L151 field_context(); L160 field_text() |
| Tres bloques de instrucciones y presupuesto de pasos | jev_ultrafast/questions.py | L3 NEXT_ACTION; L16 TARGET; L21 TEXT_VALUE; L26 MAX_STEPS = 60 |
| Instantánea del DOM, controles numerados, guarda de frescura | jev_ultrafast/snapshot.js | L1–107 (archivo completo) |
| Conexión con el navegador y ejecución | jev_ultrafast/browser.py | L16 StalePage; L20 Browser clase |
| Inspector local | jev_ultrafast/demo.py | L44 command(); L70 Handler; L131 main() |
| Documento de diseño (operaciones+objetivos dinámicos, runtime, límites) | docs/design.md | — |
| Detalles de medición y limitaciones | docs/performance.md | Citado en el README |