TL;DR
- La infraestructura del navegador para agentes de IA ejecuta acciones del navegador y devuelve observaciones de una sesión autorizada.
- Define una herramienta pequeña tipada que acepte entradas de tareas aprobadas en lugar de JavaScript arbitrario, selectores o destinos del modelo.
- Trata el contenido de la página como datos. Concede autoridad al agente a través de la política de la aplicación, con el texto de la página tratado como contenido no confiable.
- Usa una conexión de tiempo de ejecución soportada y haz que la aplicación verifique la página objetivo y la salida del negocio.
- Mantén los errores de modelo/herramienta, los errores del sitio y las fallas del ciclo de vida de la sesión distintos para que los reintentos tengan el alcance correcto.
- Libera una sesión administrada a través de su interfaz de ciclo de vida después de la tarea y verifica la terminación.
¿Qué hace una capa de ejecución del navegador para un agente de IA?
Una capa de ejecución del navegador proporciona las funciones de cliente y tiempo de ejecución que convierten una solicitud permitida del agente en trabajo observable del navegador. Puede abrir una aplicación, esperar una señal significativa y devolver un pequeño resultado para que el agente o controlador lo utilice. La aplicación circundante aún decide qué solicitudes están permitidas y qué prueba la finalización. Nstdata proporciona infraestructura del navegador que se puede adjuntar a través del flujo de trabajo de CDP documentado.
Imagina un asistente de liberación interna que necesita el estado de una compilación conocida en una página de staging autorizada. El agente necesita un resultado como aprobado o fallido. Es posible que el navegador deba renderizar primero un panel de estado de JavaScript. Mantén los tokens de control y la autoridad de navegación en el trabajador. Devuelve solo una observación verificada y con alcance al modelo. Una función estrecha puede realizar la tarea con un destino explícito y devolver solo el estado verificado. La comparación de la API de navegador en la nube y Crawl explica el límite entre la ejecución interactiva y la adquisición de contenido impulsada por URL.
¿Qué componentes debería poseer su aplicación?
Su aplicación debería poseer el contrato de tarea, la autorización de acción, las verificaciones de aceptación y la decisión de detener. El cliente del navegador interpreta la llamada permitida y realiza la acción de UI seleccionada. El proveedor posee partes documentadas de aprovisionamiento de tiempo de ejecución y observa su propio ciclo de vida. Un límite útil comienza en el trabajador, antes de que cree canales para salidas arbitrarias del modelo.
| Componente | Responsabilidad | Salida observable |
|---|---|---|
| Agente | Proponer una tarea de las herramientas aprobadas | Valor de solicitud tipada |
| Política y enrutamiento | Verificar identidad, objetivo permitido y acción permitida | Aceptar o rechazar con una razón segura |
| Trabajador del navegador | Cargar la página esperada y ejecutar la operación limitada | Un marcador de página verificado o error categorizado |
| Validador de aplicación | Verificar los datos y su asociación con el trabajo | Resultado aceptado o reconciliación |
| Propietario del ciclo de vida | Detener el navegador administrado y reconciliar el uso | Estado de sesión terminal |
Mantén la lista de permitidos limitada a las herramientas que la aplicación necesita realmente. Evita agregar navegación no restringida para llenar vacíos en el diseño de herramientas. Si la operación solicitada se encuentra fuera del alcance aprobado, devuelve un rechazo seguro o envía el trabajo para una revisión autorizada por un humano. Consulta la guía de OWASP sobre la agencia excesiva.
¿Cómo se construye una herramienta de navegador limitada para una tarea?
Construye una herramienta que acepte una acción autorizada, valide su ítem de trabajo y devuelva una observación estructurada. El ejemplo lee un estado de compilación sintético de un fixture y rechaza una solicitud de envío. Requiere Node.js 22, playwright-core@1.65.1, y los archivos correspondientes. Comienza node fixture.mjs para una ejecución local e instala Chromium con npx playwright-core install chromium. Una ejecución administrada requiere un espacio de trabajo autorizado, una sesión lista y un fixture aprobado equivalente accesible por el navegador administrado.
Paso 1. Define la solicitud permitida
Dale al llamador una pequeña forma de solicitud, como { action: "readBuildStatus", build: "fixture-42" }. Valida la operación y rechaza los campos adicionales en el límite. Deriva el destino de la configuración de la aplicación y de la operación misma. Para una integración de producción con más de una compilación permitida, busca los IDs de compilación autorizados antes de construir una ruta.
Paso 2. Prepara un adjunto del navegador
Establece el origen de destino aprobado del controlador y conéctate a través de la interfaz del cliente documentada. Para una ejecución administrada, establece NSTDATA_API_KEY, NSTDATA_SESSION_ID, y NSTDATA_TEAM_ID si el contexto de tu equipo lo requiere. El ayudante de conexión verifica que la sesión esté lista y se adjunta con la credencial devuelta. El ejemplo local puede lanzar un Chromium aislado directamente. La rama del servicio en vivo requiere autorización del espacio de trabajo. La tarea principal fue verificada en Chromium local y un tiempo de ejecución de CDP local temporal.
const root = 'https://api.nstdata.io/api/v1/cloud-browser'; export async function api(method, path, body) { const key = process.env.NSTDATA_API_KEY; if (!key) throw new Error('Set NSTDATA_API_KEY'); const headers = { 'x-api-key': key }; if (process.env.NSTDATA_TEAM_ID) headers['x-team-id'] = process.env.NSTDATA_TEAM_ID; if (body) headers['content-type'] = 'application/json'; let response; try { response = await fetch(root + path, { method, headers, redirect: 'error', body: body ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(20_000), }); } catch { throw Object.assign(new Error('API transport failed; reconcile the original operation'), { retryable: true }); } const retryable = response.status === 429 || response.status >= 500; let result; try { result = await response.json(); } catch { throw Object.assign(new Error('Invalid API JSON'), { retryable }); } if (!response.ok || result.err === true || result.success === false) { throw Object.assign(new Error(`Cloud Browser API HTTP ${response.status}`), { retryable }); } if (!result.data) throw new Error('Missing API data'); return result.data; } export async function connection(id) { if (!id) throw new Error('Set NSTDATA_SESSION_ID'); const path = `/sessions/${encodeURIComponent(id)}`; const session = await api('GET', path); if (session.state !== 'ready') throw new Error(`Session is ${session.state}, not ready`); const c = await api('POST', path + '/automation-credentials'); if (c.sessionId !== id || !c.headerName || !c.accessToken || !(Date.parse(c.expiresAt) > Date.now()) || new URL(c.cdpUrl).protocol !== 'wss:') { throw new Error('Invalid or expired CDP credentials'); } return { endpoint: c.cdpUrl, headers: { [c.headerName]: c.headerName.toLowerCase() === 'authorization' ? `Bearer ${c.accessToken}` : c.accessToken }, }; } export async function endpoint() { // An isolated local CDP endpoint can test the client without managed credentials. if (process.env.LOCAL_CDP_URL) { const url = new URL(process.env.LOCAL_CDP_URL); if (!['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)) { throw new Error('LOCAL_CDP_URL must use loopback'); } return { endpoint: url.href, headers: {} }; } return connection(process.env.NSTDATA_SESSION_ID); }
import { chromium } from 'playwright-core'; import { endpoint } from './cloud-api.mjs'; export async function withPage(task) { const origin = new URL(process.env.APP_ORIGIN ?? 'http://127.0.0.1:4173'); const remote = Boolean(process.env.LOCAL_CDP_URL || process.env.NSTDATA_SESSION_ID); if (!remote && origin.hostname !== '127.0.0.1') throw Error('Use the local fixture for local runs'); const connection = remote ? await endpoint() : null; const browser = connection ? await chromium.connectOverCDP(connection.endpoint, { headers: connection.headers, timeout: 15_000 }) : await chromium.launch({ args: ['--no-proxy-server'] }); let page; try { const context = remote ? browser.contexts()[0] : await browser.newContext(); if (!context) throw Error('Expected a browser context'); page = await context.newPage(); page.setDefaultTimeout(8_000); page.setDefaultNavigationTimeout(10_000); return await task(page, origin); } finally { try { await page?.close(); } finally { await browser.close(); } } }
Paso 3. Ejecutar la operación del tamaño de una tarjeta
Guarde el módulo de tarea como agent.mjs. Ejecute node agent.mjs contra el elemento local. El script compara la URL de la página actual con la ruta del elemento seleccionado, verifica el encabezado y el marcador de tarea, y devuelve solo un valor reconocido. La operación rechazada devuelve rejected_action sin dirigir el navegador a una nueva página. Use el referencia de Playwright BrowserType para los límites de conexión y la referencia de Locator para seleccionar el resultado.
import assert from 'node:assert/strict'; import { withPage } from './browser.mjs'; async function readBuild(page, approvedOrigin, request) { if (request?.action !== 'readBuildStatus' || request.build !== 'fixture-42' || Object.keys(request).length !== 2) return { status: 'rejected_action' }; const route = new URL('/status', approvedOrigin); const response = await page.goto(route.href, { waitUntil: 'domcontentloaded' }); if (!response?.ok() || page.url() !== route.href) return { status: 'unexpected_page' }; await page.getByRole('heading', { name: 'Build status', exact: true }).waitFor(); const field = page.locator('output[data-build="fixture-42"]'); const observed = (await field.textContent()).trim(); if (!['passed', 'failed'].includes(observed)) return { status: 'invalid_result' }; return { status: 'observed', build: request.build, result: observed }; } await withPage(async (page, origin) => { const allowed = await readBuild(page, origin, { action: 'readBuildStatus', build: 'fixture-42' }); const rejected = await readBuild(page, origin, { action: 'submit', build: 'fixture-42' }); assert.deepEqual(allowed, { status: 'observed', build: 'fixture-42', result: 'passed' }); assert.deepEqual(rejected, { status: 'rejected_action' }); console.log(JSON.stringify({ allowed, rejected })); });
Trate la comparación exacta de URL como una verificación para este fixture fijo. Los trabajos de producción necesitan que se haga cumplir la política de red y navegación en el límite de ejecución apropiado, incluido el comportamiento de redirección y cualquier subsolicitud adicional de la que dependa la aplicación. Una aserción post-navegación por sí sola no puede hacer cumplir la salida. Mantenga el ejemplo en el origen de prueba fijo para el que fue diseñado.
Paso 4. Grabe y cierre el trabajo
Registre el nombre de la acción, la referencia de la construcción validada, la categoría del resultado y el identificador de tiempo de ejecución. Mantenga las credenciales de conexión y el texto de la página arbitrario fuera del contexto y los registros del modelo generalizado. Cierre cualquier página que el trabajo creó. El controlador detiene el navegador gestionado y verifica su estado terminal. Ciclo de vida de la sesión del navegador en la nube.
¿Cómo evita que el contenido de la página amplíe la autoridad de un agente?
Evite que el contenido de la página amplíe la autoridad haciendo cumplir políticas en la aplicación y limitando lo que la herramienta del navegador acepta. Un banner o instrucción dentro de un sitio puede describir cómo usar una página. Una carga externa, un nuevo destino o acceso adicional a la cuenta requiere autorización a nivel de aplicación. La aplicación debe elegir el destino permitido y las operaciones permitidas antes de que se cargue una página.
Devuelva una salida estructurada al modelo siempre que la acción lo permita. Para una herramienta de estado, devuelva el ID de trabajo conocido, los valores de estado legales y una razón de falla segura. Para una tarea que necesita texto, mantenga su procedencia y téngalo como un documento para interpretar. Si una tarea necesita genuinamente un efecto secundario, defina una operación tipada separada y autorícela explícitamente. Un fixture de prueba interna y datos sintéticos hacen que las verificaciones de límite sean lo suficientemente discretas para repetir.
La guía de transferencia de operador da un patrón para pausar en un límite de flujo de trabajo real. Una vez que una persona autorizada termina, valide el estado de página esperado antes de reanudar la automatización. Mantenga el controlador que posee la terminación disponible incluso si el agente deja de responder.
¿Cómo encaja Nstdata Cloud Browser en la pila de agentes?
Nstdata Cloud Browser proporciona navegadores en la nube gestionados para la automatización de navegadores y agentes de IA. Su aplicación puede adjuntar Playwright a una sesión de propiedad mientras retiene las verificaciones de permiso de herramienta y su propio estado de progreso. Live View puede ser útil en un flujo de trabajo aprobado que requiere que una persona inspeccione o continúe una página. Los diagnósticos disponibles pueden ayudar a separar el adjunto del navegador de las fallas de la página o la aplicación. Para tareas que requieren contenido de URL pública para tareas de ingestión, evalúe Nstdata Crawl, una API de rastreo web para datos listos para LLM.
- Adjunto documentado. Use la API comercial para preparar una sesión de propiedad y darle al trabajador la credencial de conexión de corta duración correcta.
- Inspección humana. Conceda a un operador autorizado solo el acceso necesario para revisar o resolver la tarea, y luego verifique un punto de control al regresar.
- Ciclo de vida de ejecución. Mantenga los pasos de detención y verificación con el controlador para que las excepciones del agente no dejen un navegador no rastreado.
- Evidencia separada. Correlacione eventos de diagnóstico permitidos con el ID de tarea de la aplicación, y mantenga artefactos protegidos fuera del contexto rutinario del modelo.
¿Qué deberías enviar antes de agregar más acciones de agente?
Envía una acción estrecha con dos resultados claros y una prueba de extremo a extremo repetible. Demuestre que el servicio puede informar el estado de construcción esperado, rechazar una operación diferente y recuperarse de un fallo conocido de página sin volver a emitir un acceso más amplio. Amplíe el vocabulario de la herramienta solo cuando la siguiente operación tenga su propia identidad, permiso, recibo y regla de limpieza.
Mida la parte de las llamadas propuestas que pasan la política, la parte que produce una observación aceptada y la parte que alcanza el cierre verificado del navegador. Si un flujo de trabajo falla antes de producir evidencia, utilice la guía de depuración de automatización de navegadores para determinar qué capa debe informar la falla.
FAQ
Q: ¿Un agente siempre necesita control total del navegador? Muchas tareas de los agentes necesitan solo una operación estructurada de lectura o aprobada. Una herramienta de navegador limitada puede cubrir esas tareas con menos autoridad y menos exposición de datos.
Q: ¿Debería un modelo obtener el punto final y el token de CDP? Mantén las credenciales de control dentro del trabajador autorizado. Devuelve un resultado seguro o una referencia de trabajo permitida al llamador.
Q: ¿Cómo puede un agente reconocer la finalización? Haz que la aplicación confirme la página esperada, lea un marcador de tarea independiente y valide el valor devuelto. Realiza el seguimiento de la terminación del navegador por separado.
Q: ¿Puede un agente reintentar acciones rechazadas o fallidas automáticamente? Reintenta solo errores transitorios clasificados con una política limitada. Las solicitudes rechazadas necesitan una nueva tarea válida, y las escrituras inciertas necesitan reconciliación antes de un reintento.
Q: ¿El ejemplo utiliza un modelo en vivo? El ejemplo ejercita la herramienta del navegador con solicitudes de fixture explícitas. Demuestra el contrato de ejecución que una integración de modelo puede llamar.





