Browser

What is @cogitator-ai/browser?Copy Anchor Link

@cogitator-ai/browser gives your agents the ability to browse the web. It wraps Playwright in a session-based API and exposes 33 tools that agents can call to navigate pages, fill forms, extract data, take screenshots, and intercept network traffic.

Everything runs through BrowserSession which manages the browser lifecycle, tabs, cookies, and optional stealth mode for anti-detection. Tools are created via browserTools() and plug directly into any Cogitator agent.

Agent
  │
  ├── browser_navigate("https://example.com")
  ├── browser_fill_form({ email: "...", password: "..." })
  ├── browser_click("#submit")
  ├── browser_screenshot()
  └── browser_get_text(".result")

InstallationCopy Anchor Link

pnpm add @cogitator-ai/browser playwright

playwright comes with the package (it is loaded when the session starts); add it yourself to pin its version. Playwright needs browser binaries — install them after adding the package:

npx playwright install chromium

Quick StartCopy Anchor Link

import { Cogitator, Agent } from '@cogitator-ai/core';
import { BrowserSession, browserTools } from '@cogitator-ai/browser';

const session = new BrowserSession({ headless: true });
await session.start();

const agent = new Agent({
  name: 'web-researcher',
  model: 'openai/gpt-6.1-sol',
  tools: browserTools(session),
  instructions: 'You browse the web to find information.',
});

const cogitator = new Cogitator({
  llm: {
    defaultModel: 'openai/gpt-6.1-sol',
    providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
  },
});

const result = await cogitator.run(agent, {
  input: 'Go to https://news.ycombinator.com and get the top 5 stories',
});

console.log(result.output);
await session.close();

Tools from browserTools() start the session on their first call, so session.start() is optional here — it just moves the browser launch out of the first tool call.

Tool ModulesCopy Anchor Link

All 33 tools are organized into 5 modules. Use browserTools(session) to get all of them, or filter by module.

Module FilteringCopy Anchor Link

Load only the modules you need:

const tools = browserTools(session, {
  modules: ['navigation', 'extraction'],
});

Individual Tool ImportCopy Anchor Link

Import module or tool factories when you want fine-grained control. Module factories return typed tuples, so each destructured tool keeps its own parameter and result types:

import { createNavigateTool, createScreenshotTool, createVisionTools } from '@cogitator-ai/browser';

const tools = [createNavigateTool(session), createScreenshotTool(session)];
const [screenshot, , findByDescription] = createVisionTools(session);

Factory-made tools expect a started session — call await session.start() before the agent runs.

Key FeaturesCopy Anchor Link

• Session management with multi-tab support, cookie persistence, proxy configuration
• Stealth mode with anti-detection evasions, fingerprint randomization, human-like behavior
• Vision tools that leverage the accessibility tree for natural language element finding
• Network interception for blocking resources, modifying requests, and capturing HAR logs
• Smart form filling that matches fields by name, placeholder, aria-label, or label text

Next StepsCopy Anchor Link

• BrowserSession — lifecycle, tabs, cookies, configuration
• Tools Reference — all 33 tools with parameters
• Stealth — anti-detection and human-like behavior
• Vision — screenshots and accessibility-based interaction
• Network — request interception and traffic capture