Intercept HTTP requests, block resources, capture HAR logs, and monitor API calls.

Overview

The network module provides 5 tools for controlling and monitoring HTTP traffic. These tools share a NetworkState instance internally that tracks interceptors and records API calls.

import { browserTools } from '@cogitator-ai/browser';

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

Or import individual tools:

import {
  createInterceptRequestTool,
  createWaitForResponseTool,
  createBlockResourcesTool,
  createCaptureHarTool,
  createGetApiCallsTool,
} from '@cogitator-ai/browser';

Request Interception

`browser_intercept_request`

Intercept HTTP requests matching a URL pattern. Three actions are available:

block — abort the request entirely
modify — continue with modified headers, body, or URL
continue — let the request through (useful for logging)

// block all analytics
{ "urlPattern": "**/analytics/**", "action": "block" }

// add auth header to API requests
{
  "urlPattern": "**/api/**",
  "action": "modify",
  "modify": {
    "headers": { "Authorization": "Bearer token123" }
  }
}

// redirect requests
{
  "urlPattern": "**/old-api/**",
  "action": "modify",
  "modify": { "url": "https://new-api.example.com/v2" }
}

Returns an interceptorId that identifies this interceptor in the internal state.

`browser_block_resources`

Block specific resource types from loading. This is a convenience wrapper over request interception. Useful for speeding up page loads.

// block images, fonts, and stylesheets for faster scraping
{ "types": ["image", "font", "stylesheet"] }

Supported types: image, stylesheet, font, media, script.

Response Monitoring

`browser_wait_for_response`

Wait for an HTTP response matching a URL pattern. Returns the response status, headers, and body.

// wait for the search API to respond
{ "urlPattern": "/api/search", "timeout": 10000 }
// returns: { url: "...", status: 200, headers: {...}, body: "..." }

`browser_get_api_calls`

Get captured XHR and fetch API calls. The tool automatically starts listening for API calls on first use. Filter by URL pattern or HTTP method.

// get all captured API calls
{}

// filter by URL
{ "urlPattern": "/api/users" }

// filter by method
{ "method": "POST" }

// both
{ "urlPattern": "/api/", "method": "GET" }

Returns an array of call records:

{
  calls: [
    {
      url: 'https://example.com/api/users',
      method: 'GET',
      status: 200,
      timing: 0,
      requestHeaders: { ... },
      responseHeaders: { ... },
    }
  ]
}

HAR Capture

`browser_capture_har`

Start or stop capturing all HTTP traffic in HAR format. On stop, returns all captured entries with full request/response details including bodies.

// start capturing
{ "action": "start" }
// returns: { capturing: true, entries: 0 }

// ... navigate, interact with pages ...

// stop and save to file
{ "action": "stop", "path": "./traffic.har.json" }
// returns: { capturing: false, entries: 47, har: [...] }

// stop without saving to file
{ "action": "stop" }
// returns entries in the response only

Each HAR entry contains:

{
  url: string;
  method: string;
  status: number;
  timing: number;
  requestHeaders: Record<string, string>;
  responseHeaders: Record<string, string>;
  responseBody: string;
}

Network Monitoring Example

An agent that monitors API traffic while browsing:

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: 'api-monitor',
  model: 'openai/gpt-4o',
  tools: browserTools(session, {
    modules: ['navigation', 'interaction', 'network', 'extraction'],
  }),
  instructions: `You monitor web application API calls.
When asked to analyze a site, navigate to it, interact with the page,
then use browser_get_api_calls to see what API requests were made.`,
});

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

const result = await cogitator.run(agent, {
  input: 'Go to https://example.com, click around, and tell me what API endpoints it calls',
});

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

Performance Optimization

Block unnecessary resources to speed up page loads during scraping:

const agent = new Agent({
  name: 'fast-scraper',
  model: 'openai/gpt-4o',
  tools: browserTools(session),
  instructions: `Before scraping, use browser_block_resources to block images, fonts,
stylesheets, and media. This speeds up page loads significantly.`,
});

Next Steps

Tools Reference — full parameter reference for all 32 tools
Stealth — anti-detection for network-monitored sites
BrowserSession — proxy configuration for network routing

Network Tools