Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns
Node.js http.Agent class
Reference for http.Agent in Node.js: connection pooling, keepAlive, maxSockets, the global agent, agent options, and how to inspect sockets in use.
An http.Agent manages the sockets used by HTTP client requests. When a request is made, the agent either hands it an idle socket to the same host and port or opens a new one, and it can limit how many sockets exist at once. With keep-alive enabled, finished sockets go back into a pool instead of being closed, which saves a TCP (and TLS) handshake per request.
Every http.request() uses the global agent, http.globalAgent, unless you pass agent in the options. Since Node.js 19 the global agent has keep-alive on. For fine control, create your own agent and share it across requests.
const agent = new http.Agent({ keepAlive: true, maxSockets: 10 }); http.get({ host: '127.0.0.1', port: 3000, agent }, (res) => res.resume());
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
new http.Agent([options])
| Option | Description |
|---|---|
keepAlive |
Keep sockets open after a request finishes so later requests can reuse them. Default false for a new Agent, but true for http.globalAgent. |
keepAliveMsecs |
Initial delay for TCP keep-alive probes on pooled sockets. Default 1000. |
maxSockets |
Maximum concurrent sockets per host:port (origin). Default Infinity. Excess requests wait in a queue. |
maxTotalSockets |
Maximum sockets across all origins. Default Infinity. |
maxFreeSockets |
Maximum idle sockets kept per origin when keepAlive is on. Default 256. |
scheduling |
'lifo' (default, reuse the most recently freed socket) or 'fifo'. |
timeout |
Socket timeout in milliseconds for sockets this agent creates. |
agentKeepAliveTimeoutBuffer |
Milliseconds subtracted from the server's Keep-Alive: timeout= hint before an idle socket is dropped. |
Properties and methods
| Name | Description |
|---|---|
agent.sockets |
Object mapping an origin key to the array of sockets in use. |
agent.freeSockets |
Same for idle pooled sockets. |
agent.requests |
Requests waiting for a socket, by origin key. |
agent.destroy() |
Closes all sockets. Do this when you are finished with a custom agent. |
agent.getName(options) |
Returns the key string for an origin (host, port, local address, family). |
agent.createConnection(options[, cb]) |
The function that makes the socket; override it for custom transports. |
agent.keepSocketAlive(socket), agent.reuseSocket(socket, req) |
Hooks that decide what happens when a socket is released and reused. |
Errors: a socket that the server closes while idle can raise ECONNRESET on the next request that reuses it; the request fails and you may retry if it is safe to repeat.
Usage notes
- Pass
agent: falseto a request to give it a brand-new agent with default settings (no pooling), which sometimes helps when debugging connection reuse problems. - Keep-alive only helps if the server cooperates. The server must not close the connection after each response.
Connection: closefrom the server disables reuse for that socket. - Always consume responses. A socket returns to the pool only after the response has been fully read (or the request destroyed). A forgotten response leaks a socket and, with
maxSocketsset, can stall every later request. maxSocketsqueues, it does not fail. Waiting requests sit inagent.requestsuntil a socket is free; that is a simple way to rate-limit fan-out.- Open pooled sockets keep the process alive. Idle keep-alive sockets are unreferenced in current Node versions, but destroy custom agents in tests and scripts anyway.
- HTTPS has
https.Agent, which extends this class with TLS options and also pools TLS sessions. fetch()uses its own pool (undici) and ignoreshttp.Agent; use an undici dispatcher to tune it.