# Network Tools

URL: https://cogitator.app/docs/browser/network

> 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.

```typescript
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:

```typescript
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.

```typescript
// 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.

```typescript
{ "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.

```typescript
// 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.

```typescript
// 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.

```typescript
// 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:

```typescript
{
  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](http://www.softwareishard.com/blog/har-12-spec/) document is written that opens in browser devtools and HAR viewers. The path must be inside the working directory.

```typescript
// 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:

```typescript
{
  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:

```typescript
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:

```typescript
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

* [Tools Reference](/docs/browser/tools) — full parameter reference for all 33 tools
* [Stealth](/docs/browser/stealth) — anti-detection for network-monitored sites
* [BrowserSession](/docs/browser/session) — proxy configuration for network routing