Agent Viewer: Live Browser Sessions for AI Agents and Automation

# Agent Viewer: Live Browser Sessions for AI Agents and Automation

When your AI agent or Playwright script runs in a remote browser, you're effectively flying blind. Logs tell you what happened, but they don't show you *why* a click missed, a selector timed out, or a page rendered incorrectly. That's where an agent viewer becomes essential infrastructure. It gives you a live, visual window into what the browser is actually doing at any given moment.

Remote Browser provides a hosted Chromium runtime with a built-in agent viewer. This isn't a marketing feature; it's a debugging tool that directly impacts task success rates. This guide explains what an agent viewer is, why it matters for production workloads, and how to use Remote Browser's viewer to keep your automation honest.

What Is an Agent Viewer?

An agent viewer is a real-time visual interface that streams the screen of a remote browser session. It's the difference between reading a Playwright trace and watching the browser execute your commands. For AI agents that make decisions based on page state, an agent viewer is the only way to verify that the agent's "perception" matches reality.

Most browser automation frameworks—Playwright, Puppeteer, Selenium—run headless by default. Headless is fast and resource-efficient, but it hides the visual context that matters for debugging. An agent viewer bridges that gap by exposing the browser's viewport over a secure WebSocket connection.

Why Your AI Agent Needs a Live Viewer

AI agents are probabilistic. They interpret page content, decide on actions, and execute them. When something goes wrong, the failure mode is often visual: a modal dialog covered a button, a lazy-loaded image shifted the layout, or a cookie banner intercepted a click. Text logs rarely capture these issues.

A live agent viewer solves this by letting you:

• Watch agent actions in real time to catch missteps before they cascade.
• Verify page state after each action, not just at the end of a task.
• Debug session persistence issues across cloud workers.
• Share the screen with teammates or stakeholders for collaborative debugging.

For teams running browser automation at scale, the agent viewer isn't a nice-to-have. It's the difference between a 95% task success rate and a 70% one, because you can actually see and fix the edge cases.

Remote Browser's Agent Viewer: How It Works

Remote Browser's agent viewer is built into every hosted Chromium session. When you connect via Playwright, Puppeteer, Selenium, or raw CDP, you get a live view of that browser instance. Here's how it fits into the architecture:

1. Session creation: You request a browser session via the Remote Browser API.
2. CDP connection: Your code connects to the session using browserType.connectOverCDP() or the equivalent.
3. Live viewer: The viewer streams the browser's viewport to your dashboard or via an embeddable iframe.
4. Interactive debugging: You can watch, pause, and even inject commands directly into the live session.

The viewer is particularly useful for debugging persistent profiles. If your agent uses a logged-in session across multiple workers, you can watch the session state carry over correctly—or spot where it breaks.

Agent Viewer vs. Traditional Debugging Tools

To understand where an agent viewer fits, compare it with the alternatives:

The agent viewer's key advantage is *liveness*. You see the browser as it exists right now, not as it was when a trace was captured. This is critical for long-running sessions where state changes over time.

How to Connect to a Remote Browser Session with a Viewer

Connecting to a Remote Browser session is straightforward if you're familiar with Playwright. The key is using connectOverCDP, which is Chromium-only per the official Playwright documentation. Here's a TypeScript example:

import { chromium } from 'playwright';
import { RemoteBrowserAPI } from '@remote-browser/sdk';

// Initialize the Remote Browser client
const api = new RemoteBrowserAPI({
  apiKey: process.env.REMOTE_BROWSER_API_KEY,
});

// Create a new browser session
const session = await api.sessions.create({
  profileId: 'persistent-profile-123',
  viewport: { width: 1280, height: 720 },
});

// Connect Playwright to the remote Chromium instance via CDP
const browser = await chromium.connectOverCDP(session.cdpUrl);

// The agent viewer is now available at session.viewerUrl
console.log(`Watch live: ${session.viewerUrl}`);

// Use the browser as you normally would
const page = await browser.newPage();
await page.goto('https://example.com');

// Your agent logic here
const heading = await page.textContent('h1');
console.log(`Heading: ${heading}`);

// Don't forget to close the session when done
await browser.close();
await api.sessions.destroy(session.id);

Once connected, you can open the viewerUrl in any browser to watch the session live. This works whether your code is running locally, in a cloud worker, or inside a Docker container.

Production Considerations for Agent Viewers

Running an agent viewer in production isn't just about opening a WebSocket. Here are the practical considerations we've learned from running browser workloads at scale:

Session Persistence Across Workers

One of the most common questions we hear is: *"How do I keep browser sessions alive across multiple cloud workers?"* The answer is that you shouldn't try to keep a session alive across workers. Instead, you should persist the *profile* and reconnect to a fresh session.

Remote Browser separates the concept of a session (the running browser instance) from a profile (the persistent state). Your agent viewer shows the current session. When that session ends, the profile retains cookies, localStorage, and other state. The next worker can start a new session with the same profile and pick up where the last one left off.

Scaling Browser Workloads Reliably

Scaling Playwright workloads reliably requires more than just adding more workers. You need to manage:

• Browser startup time: Cold starts can take 5-10 seconds. Remote Browser pre-warms sessions to reduce this.
• Resource isolation: Each session runs in its own container, so a memory leak in one agent doesn't affect others.
• Connection stability: CDP connections can drop. Your code should handle reconnection gracefully.

The agent viewer helps with all three. You can watch a session start, verify it's healthy, and debug connection issues in real time.

Chromium Sandbox Settings

If you're running Chromium in a containerized environment, you've likely encountered the --no-sandbox flag issue. The Playwright documentation explicitly notes that Chromium's sandbox should not be disabled in production. Remote Browser handles this by running each session in an isolated container with the sandbox properly configured.

This is a subtle but important detail. Many teams disable the sandbox to get things working locally, then ship that configuration to production. That's a security risk. With a hosted runtime, you get proper sandboxing without having to manage it yourself.

When an Agent Viewer Isn't Enough

An agent viewer is a powerful debugging tool, but it has limits. Here's what it won't tell you:

• Why the agent made a decision: The viewer shows actions, not reasoning. You'll need agent logs for that.
• Network-level issues: If a request fails due to DNS or proxy problems, the viewer shows the error page, not the cause.
• Performance bottlenecks: The viewer shows the browser, but not the CPU/memory usage of the underlying container.

For these, you need complementary tooling. Remote Browser provides session logs and performance metrics alongside the viewer. Together, they give you a complete picture of what happened and why.

Agent Viewer Use Cases Beyond Debugging

While debugging is the primary use case, an agent viewer has other practical applications:

Compliance and Auditing

If your agents perform financial transactions or handle personal data, you may need to record what happened. The agent viewer can be paired with session recording to create an audit trail. This is useful for regulated industries where you need to prove what your automation did.

Customer Support

When an agent fails to complete a task for a customer, support teams can use the viewer to see exactly what went wrong. Instead of asking the customer to reproduce the issue, support can watch the recorded session and diagnose the problem directly.

Training and QA

For teams building browser automation frameworks, the agent viewer is an excellent training tool. New developers can watch experienced agents navigate complex workflows, learning best practices by observation.

Security Considerations for Live Viewers

Streaming a browser session live introduces security considerations. Here's how Remote Browser handles them:

• Authentication: Viewer URLs are time-limited and require the same API key used to create the session.
• Access control: You can revoke viewer access at any time by ending the session.
• Data isolation: Each session's viewer stream is isolated from other sessions. There's no cross-session data leakage.

If you're embedding the viewer in your own dashboard, you'll need to handle authentication on your side. The viewer URL is a capability URL—anyone with the link can view the session. Treat it like a secret.

Choosing the Right Agent Viewer for Your Stack

Not all agent viewers are created equal. When evaluating options, consider:

Remote Browser's agent viewer includes all of these features. It's not an afterthought; it's a core part of the runtime.

Getting Started with Remote Browser's Agent Viewer

If you're ready to add an agent viewer to your browser automation stack, here's a quick roadmap:

1. Sign up for a Remote Browser account and get your API key.
2. Create a session using the API or SDK.
3. Connect your Playwright, Puppeteer, or Selenium code via CDP.
4. Open the viewer URL to watch your session live.
5. Debug issues as they happen, rather than after the fact.

For more details on the API, check the documentation. If you're evaluating costs, see the pricing page for current rates.

Conclusion: The Agent Viewer Is a Production Necessity

Running AI agents or browser automation without an agent viewer is like debugging code without a print statement. It's possible, but it's unnecessarily difficult. The agent viewer gives you eyes on the browser, which is essential for diagnosing the visual failures that plague web automation.

Remote Browser's agent viewer is built into every session, so you don't need to set up separate streaming infrastructure. It works with the tools you already use—Playwright, Puppeteer, Selenium—and it's designed for production workloads, not just local development.

If you're building browser automation at scale, start with an agent viewer. It will save you hours of debugging time and help you catch issues before they become customer-facing failures. For a deeper dive into how remote browsers fit into your AI agent architecture, read our guide on remote browsers for AI agents or explore remote browser online for a practical overview.

The web is visual. Your debugging tools should be too.