Una contraseña pegada en el chat deja de ser una contraseña. Termina en mensajes, en trazas y en cada sistema que los guarda. Managed Deep Agents toma la otra ruta. El agente obtiene un navegador alojado en su propio sandbox de LangSmith, maneja páginas con cuatro herramientas que la plataforma agrega para él y entrega la ventana a una persona cuando aparece un muro de inicio de sesión, un CAPTCHA o una verificación de dos factores. La persona inicia sesión en el propio sitio. El agente nunca ve la credencial.
El uso del navegador llegó en Managed Deep Agents v0.10, puesto en beta pública el 29 de octubre de 2026. La documentación cubre dos trabajos para él: trabajo en sitios sin una API usable, como un flujo de reserva, y prueba de una aplicación mediante su propia interfaz después de un cambio de código. LangChain dice que sus herramientas de navegador pasaron el 90 por ciento de 100 tareas de WebVoyager por 1.98 dólares en total. Esa es una afirmación de la empresa desde su propia prueba, no una promesa sobre tus sitios. Este tutorial construye la configuración en Python y demuestra la entrega con una tarea que tú elijas.
Lo que vas a construir o aprender
Terminarás con un Managed Deep Agent desplegado que puede navegar, hacer clic, llenar formularios e inspeccionar páginas por su cuenta. Sabrás cómo activar el navegador con un archivo, cómo elegir quién comparte un inicio de sesión y cómo recuperar la ventana, iniciar sesión tú mismo y devolver el control para que el agente retome donde se detuvo.
El navegador no es una ventana local y nada se ejecuta en tu computadora. Managed Deep Agents lo ejecuta de forma remota, en un sandbox aparte del sandbox del agente, y adjunta sus herramientas cuando encuentra tu declaración. Las capturas de pantalla pertenecen al mismo conjunto de herramientas, y guardar un archivo de captura de pantalla necesita un sandbox de agente, mientras que navegar en sí no lo necesita.
Antes de empezar
Elige un sitio de bajo riesgo para la primera ejecución. Usa una cuenta de prueba donde el sitio ofrezca una, y una tarea que puedas permitirte repetir. Un agente de navegador puede hacer clic en el control incorrecto en una página que ha leído mal, y una reserva o una compra hecha en el hilo incorrecto sigue siendo una reserva o una compra.
El alcance es una decisión de uso compartido, así que tómala antes de empezar. El alcance de hilo mantiene un inicio de sesión dentro de una conversación. El alcance de usuario lleva a una persona y sus inicios de sesión a través de todas las conversaciones de esa persona, lo que es conveniente y pertenece a tu política de datos si otras personas usarán el agente.
Paso 1: Crea el proyecto
Acción: crea el proyecto con la CLI mda del paquete managed-deepagents, y luego muévete a la carpeta nueva.
uvx --from managed-deepagents mda init browser-agent
cd browser-agent
Resultado esperado: la CLI crea la estructura del proyecto para un Managed Deep Agent en Python en la carpeta browser-agent. Cada archivo posterior en este tutorial va dentro de ese proyecto, y la declaración del navegador en el Paso 3 va en su raíz.
Paso 2: Agrega tus claves y define las instrucciones
Acción: abre el archivo .env en la raíz del proyecto y agrega tu clave de proveedor de modelo y tu clave de LangSmith como marcadores aquí, y luego reemplázalas con tus valores reales solo en tu propia computadora.
OPENAI_API_KEY=your-model-provider-key
LANGSMITH_API_KEY=your-langsmith-api-key
La guía rápida usa OpenAI por defecto. Para Anthropic, Google o Microsoft Foundry, define los valores de proveedor correspondientes. Tu clave de LangSmith viene de Settings, luego API Keys, luego Create API Key en LangSmith. No confirmes el archivo .env en el control de versiones.
Después, abre instructions.md y dile al agente cómo tratar un muro de inicio de sesión. Agrega una regla simple en tus propias palabras en esta línea:
When a site needs a login, a CAPTCHA, or two factor authentication, request a browser handoff and explain why you need it. Never ask me to paste a password or a code into chat.
Resultado esperado: el proyecto tiene ambas claves en .env, y sus instrucciones nombran la entrega como la ruta para superar un muro de inicio de sesión. Cuando despliegas, Managed Deep Agents sincroniza las instrucciones con LangSmith Context Hub, donde puedes actualizarlas sin un redespliegue.
Paso 3: Declara el navegador en la raíz del proyecto
Acción: crea un archivo llamado browser.py en la raíz del proyecto, junto a agent.py, con este contenido exacto para la v0.10:
from managed_deepagents import define_browser
browser = define_browser(scope="thread", idle_ttl_seconds=600)
Resultado esperado: la CLI descubre el archivo raíz y Managed Deep Agents agrega cuatro herramientas al agente por su cuenta: browser_snapshot lee el árbol de accesibilidad de la página y etiqueta elementos con ID, browser_run navega e interactúa mediante JavaScript o lotes de acciones contra esos ID, browser_screenshot captura la página y browser_handoff le da a una persona el control de la ventana. No pongas la declaración en ningún otro lugar. La documentación es contundente en este punto: una declaración dentro de una carpeta browser/ o sandbox/ no activa el soporte de navegador.
Dos opciones hacen el trabajo real en esa única llamada:
| Opción | Predeterminado | Lo que controla |
|---|---|---|
scope | "thread" | Quién comparte el navegador y sus inicios de sesión |
idle_ttl_seconds | 600 | Segundos sin actividad antes de que el navegador se detenga; la documentación acepta 60 a 86400 |
Elige el alcance según el trabajo, no por costumbre:
| Alcance | Estado del navegador | Úsalo para |
|---|---|---|
"thread" | Un navegador por conversación, compartido por participantes autorizados en sus turnos, sin cookies ni inicios de sesión de otros hilos | Probar un cambio de aplicación en una conversación, o cualquier tarea donde un inicio de sesión debería quedarse en su lugar |
"user" | Un navegador por persona autenticada, con una ventana separada para cada hilo y cookies e inicios de sesión compartidos entre esa persona y sus hilos | Reutilizar un inicio de sesión de sitio entre conversaciones, para que el agente pida un inicio de sesión una vez |
Para usar el alcance de usuario, cambia una palabra en el mismo archivo:
browser = define_browser(scope="user", idle_ttl_seconds=600)
El estado de inicio de sesión compartido no es aislamiento de cuenta. En alcance de usuario, un cierre de sesión o un cambio de cuenta en un hilo puede afectar a esa persona y sus otros hilos, así que coordina reservas y compras entre conversaciones. Terminar una ejecución libera el cliente, no el inicio de sesión; el tiempo de inactividad detiene el navegador en lugar de cerrar la sesión, y un sitio aún puede expirar la sesión por su lado.
Paso 4: Ejecuta localmente y envía una tarea de navegador
Acción: instala las dependencias del proyecto e inicia el agente en LangSmith Studio.
uv sync
uv run mda dev
Resultado esperado: mda dev carga las claves desde .env, inicia un Agent Server local y abre el agente en Studio. Ahora envía una tarea que necesite el navegador y que llegue a un inicio de sesión a propósito, con tu propio sitio de prueba y cuenta de prueba:
Go to the site I name in this thread and complete the task I describe. If the site asks for a login, a CAPTCHA, or two factor authentication, hand the browser to me and explain why.
Resultado esperado: en la traza de Studio, el agente llama a las herramientas de navegador en lugar de adivinar el contenido de la página. Toma una instantánea para leer la estructura de la página, ejecuta acciones contra los ID de la instantánea y se detiene en el muro de inicio de sesión en lugar de escribir a su alrededor. Toma una instantánea fresca después de cada navegación en tus propias instrucciones y pruebas, porque los ID de elementos quedan obsoletos a medida que las páginas cambian.
Paso 5: Toma la entrega y devuelve la ventana
Acción: cuando el agente te necesita, llama a browser_handoff(reason) y te da el control de su ventana de navegador de hilo. Trabaja la entrega en este orden:
- Lee la razón en la tarjeta de entrega. En Studio la tarjeta dice The agent needs you in the browser e incrusta el navegador, con una opción para abrirlo en una pestaña nueva. Canales como Slack muestran un enlace al mismo navegador remoto, y un cliente personalizado debe mostrar el artefacto de entrega para mostrar cualquiera de las dos formas.
- Inicia sesión dentro de esa ventana, en el propio sitio. Ingresa credenciales directamente en el sitio web, no en el chat, y termina cada paso de autenticación que el sitio pida, incluido un CAPTCHA o una verificación de dos factores.
- Haz clic en Hand back en la ventana del navegador cuando termines.
Resultado esperado: el agente recibe un aviso de que el control regresó, inspecciona la página actual para revisar si el inicio de sesión funcionó y continúa la tarea en el navegador ahora con sesión iniciada. Mientras tú sostienes la ventana, el agente y sus herramientas de navegador no pueden actuar en ella. La llamada de entrega regresa de inmediato, así que el agente puede hacer otro trabajo mientras espera. El enlace expira después de 15 minutos; la expiración termina la entrega y no demuestra nada sobre la tarea en sí. Pedir una entrega nueva reemplaza el enlace antiguo.
Paso 6: Despliega el agente
Acción: despliega el mismo proyecto en LangSmith.
uv run mda deploy
Resultado esperado: Managed Deep Agents empaqueta el proyecto y lo ejecuta como un despliegue alojado en LangSmith Agent Server. Cuando el despliegue termina, la CLI imprime la URL del panel de despliegue. Ábrela, confirma que el despliegue muestra un estado listo y envía la misma tarea de navegador del Paso 4 en el agente alojado. Mantén el archivo raíz browser.py en su lugar para cada despliegue. Activa el soporte de navegador e instala las dependencias de navegador del despliegue, y ningún ajuste posterior puede agregar un navegador sin él.
Una opción a nivel de ejecución vale la pena conocerla. En una fábrica de grafos puedes definir browser para una sola ejecución para elegir un alcance o tiempo de inactividad diferente, y pasas una definición de navegador, no una instancia de middleware. Para desactivar el navegador en una ejecución, pasa browser=None en Python o browser: null en TypeScript. Las definiciones estáticas de agente mantienen su ajuste de navegador en el archivo de declaración del Paso 3.
Verificación
Ejecuta estas comprobaciones en Studio y cuenta la instalación como funcional solo cuando las cuatro pasen.
Primero, la traza muestra trabajo real de navegador. El agente llama a browser_snapshot y browser_run para la tarea, no una obtención de texto simple de la página. Segundo, la entrega se activa en el momento correcto. En el muro de inicio de sesión aparece una tarjeta o enlace con una razón, y ninguna contraseña o código tuyo aparece en ninguna parte del chat o la traza. Tercero, la reanudación funciona. Después de Hand back, el agente inspecciona la página, informa el estado de sesión iniciada que encuentra y termina la tarea en el mismo hilo. Cuarto, el alcance coincide con tu elección. Inicia un hilo nuevo y pide el mismo sitio: en alcance de hilo el agente empieza sin inicio de sesión y pide una entrega fresca, y en alcance de usuario la misma persona y su ventana nueva pueden reutilizar el inicio de sesión.
Solución de problemas
| Problema | Causa probable | Solución |
|---|---|---|
| No aparecen herramientas de navegador en la traza | browser.py está en la carpeta incorrecta, o falta la exportación nombrada browser | Mueve el archivo a la raíz del proyecto, mantén la exportación nombrada del Paso 3 y ejecuta uv run mda dev de nuevo |
| El enlace de entrega ha expirado | Pasó la ventana de 15 minutos antes de que terminara el inicio de sesión | Pídele al agente una entrega nueva; la solicitud nueva reemplaza el enlace antiguo |
| El agente no se reanuda después de Hand back | Una aprobación separada en la conversación aún espera, o el agente perdió el aviso | Completa primero la aprobación en espera; si el agente sigue inactivo, envíale un mensaje nuevo en el mismo hilo |
| Un inicio de sesión nunca pasa a una conversación nueva | El navegador se ejecuta en alcance de hilo | Cambia scope a "user" en browser.py cuando la reutilización entre hilos es lo que quieres, y redespliega |
| Un inicio de sesión se filtra entre trabajo que querías separado | El navegador se ejecuta en alcance de usuario, así que los hilos comparten cookies e inicios de sesión | Vuelve a alcance "thread" para trabajo aislado, y trata cada hilo como su propia sesión |
| Las acciones fallan o apuntan al elemento incorrecto | Los ID de instantánea quedaron obsoletos después de que cambió la página | Toma un nuevo browser_snapshot después de la navegación y ejecuta acciones contra los ID frescos |
| Una captura de pantalla no se guarda en un archivo | Guardar archivos de captura de pantalla necesita un sandbox de agente, mientras que navegar solo no lo necesita | Mantén el sandbox del proyecto en su lugar, o usa capturas de pantalla en la respuesta sin una ruta guardada |
Próximos pasos
Apunta la misma instalación a la prueba de aplicaciones, el segundo trabajo que la documentación nombra para el uso del navegador. Una conexión privada puede unir los sandboxes del navegador y del agente, para que el agente pueda iniciar una aplicación en su propio sandbox y manejarla mediante el navegador sin una URL pública para la aplicación. Mantén el alcance de hilo para ese trabajo, para que cada conversación de prueba obtenga un navegador aislado y un estado de inicio de sesión limpio.
Ajusta los dos números que ahora son tuyos antes de compartir el agente. Eleva idle_ttl_seconds para tareas largas con pasos humanos lentos, y bájalo para tareas cortas donde un navegador con sesión iniciada que permanece es riesgo puro. Cuando otras personas empiecen a usar el agente, escribe la elección de alcance y su uso compartido de inicios de sesión en las notas que les des, en palabras sencillas, antes de que la primera entrega los sorprenda.
Pasos, comandos, reglas de alcance y comportamiento de entrega verificados contra la documentación de LangChain para el uso del navegador de Managed Deep Agents y la guía rápida de Python, octubre de 2026. Este procedimiento se verificó contra esos documentos; no se ejecutó de extremo a extremo contra un despliegue vivo de LangSmith en esta ejecución, así que haz la primera pasada con una cuenta de prueba como está escrito.
Fuentes
- Capturas de pantalla: LangChain
FIN DE LA TRANSMISIÓN
Mantén la curiosidad. Cuestiónalo todo.
