Skip to main content
Start with the Runloop Quickstart to use the examples below.

​
Introduction

This guide will walk you through using the Runloop SDK to control a browser inside a Runloop Devbox. The Runloop API provides a browser-ready Devbox, enabling AI agents to interact with web pages programmatically.
1

Setup Your Environment

Follow the instructions in the Runloop Quickstart to set up your environment to use the Runloop SDK.
2

Create a Devbox and Start the Browser

Set up your browser-ready Devbox and obtain the connection details:
# Create a Devbox with a browser instance
browser = runloop.api.devboxes.browsers.create()

# Wait for the Devbox to be fully running
devbox = runloop.devbox.from_id(browser.devbox.id)                             
await devbox.await_running()

# View your remote browser here:
print(browser.live_view_url)

# Connect to your browser here:
print(browser.connection_url)
The URLs above are both to localhost by default, and will be visible only inside the devbox. This is all you need if you are running your AI agent to control the browser from within the Devbox. If you need to access either URL remotely, you will need to also configure a tunnel.
3

Programmatically Controlling the Browser

To interact with the browser, you can use automation tools like Selenium, Puppeteer, or Playwright. Here’s an example using Playwright’s Chrome DevTools Protocol (CDP):
from playwright.async_api import async_playwright

# Initialize playwright context manager 
playwright = await async_playwright().start()

# Connect to your remote browser and create browser context
browser = await playwright.chromium.connect_over_cdp(url)
context = await browser.new_context()

# Accesses pages in the browser context's list of pages
page = context.pages[0]
4

Defining a Browser Tool for Your AI Agent

You can create custom tools for AI agents to interact with the browser programmatically. Here’s an example of a navigation tool using Playwright:
from playwright.async_api import async_playwright

class NavigateTool:
    async def __call__(self, *, url: str):
        async with async_playwright() as p:
            browser = await p.chromium.launch()
            page = await browser.new_page()
            await page.goto(url)
            content = await page.content()
            await browser.close()
            return {
              "output": f"Navigated to {url}",
              "content": content[:500]
            }

    def to_params(self):
        return {
            "name": "navigate_tool",
            "description": "Navigates to a URL and retrieves content.",
            "input_schema": {
                "type": "object",
                "properties": {"url": {"type": "string"}},
                "required": ["url"],
            },
        }
5

Passing Tools to an AI Agent

Now you can pass this tool to an AI agent, enabling it to use the browser autonomously:
import Anthropic

anthropic_client = Anthropic(
    api_key="your-anthropic-api-key")

tool_instance = NavigateTool()

response = client.messages.create(
    model=model,
    max_tokens=max_tokens,
    messages=messages,
    tools=[tool_instance.to_params()]
)
Different LLM providers have their own specific formats and requirements for defining and passing tools. Make sure to reference your LLM provider’s documentation for the correct implementation details of tool schemas and function calling.
6

Properly Freeing Resources

To ensure efficient resource management, always shut down the Devbox when you’re done:
await devbox.shutdown()

​
Additional Resources