agent-base 9.x

Complete instructions

Verified against agent-base@9.0.0 on 2026-09-08. 3 of 3 examples executed.

agent-base

Version and module shape

This skill targets agent-base 9.x. It is ESM-only and requires Node.js 20 or newer. Import the named Agent class and helpers:

import { Agent, json, req, toBuffer } from 'agent-base';

Do not use the old CommonJS/default-export form:

const agent = require('agent-base');

That was the v6 shape. The v7 API removed the default export and introduced the named abstract Agent class.

Agent subclass contract

Agent extends Node's http.Agent. A subclass must implement:

connect(
  req: http.ClientRequest,
  options: AgentConnectOpts
): Promise<Duplex | http.Agent> | Duplex | http.Agent;

connect() may return:

• a Duplex socket;
• another http.Agent, delegating connection handling; or
• a promise resolving to either of those.

The options include secureEndpoint: boolean, which distinguishes HTTPS from HTTP connection requests. The resulting agent is passed to Node's http or https APIs through their { agent } option.

import assert from 'node:assert/strict';
import { PassThrough } from 'node:stream';
import { Agent } from 'agent-base';

class LocalAgent extends Agent {
  connect(_request: never, options: { secureEndpoint: boolean }) {
    assert.equal(options.secureEndpoint, false);
    return new PassThrough();
  }
}

const agent = new LocalAgent({ keepAlive: true });
assert.ok(agent instanceof Agent);
assert.equal(agent.options.keepAlive, true);

const socket = agent.connect({} as never, { secureEndpoint: false });
assert.ok(socket instanceof PassThrough);

The package is an adapter, not a request runner. In a real request, pass the subclass instance to Node's http.get() or https.get() as { agent }. The connection implementation normally returns a socket created by the appropriate networking API, or returns another agent when delegation is needed.

Version 9's createSocket agent detection uses duck typing. This matters when delegating to agent implementations that are not instances of Node's http.Agent, such as tunnel-agent's TunnelingAgent; do not rely on the older strict-instance behavior.

toBuffer()

toBuffer(readable) consumes a readable stream and resolves to a Buffer containing its bytes. Provide Buffer or other byte chunks to the readable stream.

import assert from 'node:assert/strict';
import { Readable } from 'node:stream';
import { toBuffer } from 'agent-base';

const result = await toBuffer(
  Readable.from([Buffer.from('hello '), Buffer.from('world')]),
);
assert.ok(Buffer.isBuffer(result));
assert.equal(result.toString('utf8'), 'hello world');

json()

json(readable) consumes a readable stream, decodes it as UTF-8, and parses it with JSON.parse.

import assert from 'node:assert/strict';
import { Readable } from 'node:stream';
import { json } from 'agent-base';

const value = await json(Readable.from([Buffer.from('{"ok":true,"count":2}') ]));
assert.deepEqual(value, { ok: true, count: 2 });

The input must contain valid JSON. Parsing failures reject with the error from JSON.parse.

req()

req(url, opts) creates and ends an HTTP or HTTPS request based on the URL and returns the http.ClientRequest with a promise-like .then method. It is intended as a small request helper; the returned thenable resolves to the response.

This helper necessarily starts a real HTTP(S) request, so it is not demonstrated with a runnable example here: examples in this skill must run without network access. Use it only in an environment where the target URL is available, and provide request options as the second argument when needed.

Common mistakes

• Importing a default export or using require('agent-base'); v9 uses the named ESM export Agent.
• Trying to instantiate Agent directly; it is abstract and requires a connect() implementation.
• Treating connect() as returning only a socket. It can return a socket, another agent, or a promise of either.
• Ignoring options.secureEndpoint when choosing HTTP versus HTTPS/TLS connection behavior.
• Passing string chunks to toBuffer() through a Node readable; use byte chunks such as Buffer or Uint8Array.
• Treating agent-base as a standalone request runner. It integrates with Node's http and https request machinery.
• Running package examples that use describe, it, or expect directly. Those are runner globals, not part of agent-base or a plain Node/Bun script.

Not covered

This skill does not cover the internal details of Node's http.Agent pooling, custom proxy protocols, TLS option construction, tunnel-agent integration beyond the v9 duck-typing change, or network-backed usage of req(). It also does not cover package development commands or the package's test suite.