Cogitator
Browser

Network Tools

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

Overview

The network module provides 6 tools for controlling and monitoring HTTP traffic. All network tools created for the same BrowserSession share one internal state: interceptors are registered on the browser context (so they apply to every tab, including tabs opened later), and API calls are recorded from the moment the session starts.

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

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

Or create them yourself — createNetworkTools(session) returns a typed tuple [intercept, waitForResponse, blockResources, captureHar, getApiCalls, removeInterceptor], or pick single factories:

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

Request Interception

browser_intercept_request

Intercept HTTP requests matching a URL pattern. urlPattern is a Playwright glob (**/api/**) or a regular expression literal (/\.(png|jpe?g)$/i). Three actions are available:

  • block — abort the request entirely
  • modify — pass the request on with modified headers, body, or URL. headers are merged into the original request headers
  • continue — let the request through unchanged

modify and continue hand the request to the next matching interceptor (route.fallback()), so overlapping rules such as browser_block_resources keep working.

// 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 can be passed to browser_remove_interceptor. action: "modify" without a modify object registers nothing and returns { interceptorId: null, warning }.

Interceptors and a running HAR capture belong to the browser context: when the session is closed and started again (or relaunched by ensureStarted()), they are gone and need to be registered again.

browser_remove_interceptor

Remove an interceptor created by browser_intercept_request or browser_block_resources. Omit interceptorId to remove all of them.

{ "interceptorId": "interceptor_1" }
// returns: { removed: ["interceptor_1"] }

{}
// returns: { removed: ["interceptor_1", "interceptor_2"] }

browser_block_resources

Block specific resource types from loading in every tab. This is a convenience wrapper over request interception and also returns an interceptorId. 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 on the active tab whose URL contains urlPattern as a substring, or matches it when it is a /regex/flags literal. Returns the response status, headers, and body ("" when the body cannot be read). timeout: 0 waits indefinitely; without it the session's actionTimeout applies.

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

browser_get_api_calls

Get XHR and fetch calls recorded since the session started (the latest 1000 are kept). Filter by URL substring or /regex/flags literal and by HTTP method (case-insensitive); pass clear: true to remove the returned calls from the history after reading them; calls the filters excluded are kept. Failed calls are recorded with status: 0 and an error message.

// get all captured API calls
{}

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

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

// both, then remove the returned calls from the history
{ "urlPattern": "/api/", "method": "GET", "clear": true }

Returns an array of call records:

{
  calls: [
    {
      url: 'https://example.com/api/users',
      method: 'GET',
      status: 200,
      timing: 84.2, // ms from request start to response end
      requestHeaders: { ... },
      responseHeaders: { ... },
    }
  ]
}

HAR Capture

browser_capture_har

Start or stop capturing the HTTP traffic of all tabs. Entries are ordered by request start; on stop the tool waits up to 2 seconds for requests that are still in flight. With path, a HAR 1.2 document is written that opens in browser devtools and HAR viewers. The path must be inside the working directory.

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

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

// stop and save to file
{ "action": "stop", "path": "./traffic.har" }
// returns: { capturing: false, entries: 47, truncated: false, har: [...], path: "/abs/traffic.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>;
  requestBody?: string;   // request post data, when present
  responseBody?: string;  // textual responses up to 1 MB
}

A capture keeps at most 5000 entries; truncated: true means more requests happened than were recorded.

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-6.1-sol',
  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-6.1-sol',
    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-6.1-sol',
  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

Vision Tools

Screenshot capture, accessibility tree traversal, and natural language element interaction.

Memory Overview

Understand how Cogitator agents persist context across conversations using pluggable memory adapters, embeddings, and knowledge graphs.

On this page

OverviewRequest Interceptionbrowser_intercept_requestbrowser_remove_interceptorbrowser_block_resourcesResponse Monitoringbrowser_wait_for_responsebrowser_get_api_callsHAR Capturebrowser_capture_harNetwork Monitoring ExamplePerformance OptimizationNext Steps