Agent

An Agent dispatches requests against multiple different origins, creating and reusing a per-origin Pool (or Client) on demand. It is the default dispatcher used by request, stream, and fetch when no explicit dispatcher is supplied.

Requests are not guaranteed to be dispatched in their order of invocation.

import { Agent, setGlobalDispatcher } from 'undici'

const agent = new Agent({ connections: 10 })
setGlobalDispatcher(agent)

class Agent extends Dispatcher

Agent keeps an internal map of origins to dispatchers. The first request to a given origin lazily creates a dispatcher through the configured factory, and subsequent requests to the same origin reuse it. Idle dispatchers are closed automatically once they have no open connections and are no longer busy.

new Agent(options?): void

Agent inherits all <PoolOptions> (and therefore all <ClientOptions>). The per-origin <Pool> it creates uses the default unlimited connections, so concurrent requests to the same origin are spread across separate <Client> instances on separate sockets.

true after agent.close() has been called.

true after agent.destroy() has been called, or after agent.close() has been called and the shutdown has completed.

Aggregate statistics for the agent, keyed by origin. Each value is the ClientStats or PoolStats object reported by the dispatcher currently serving that origin. Origins whose dispatcher does not expose stats are omitted.

import { Agent } from 'undici'

const agent = new Agent()
await agent.request({ origin: 'http://localhost:3000', path: '/', method: 'GET' })
console.log(agent.stats)
// { 'http://localhost:3000': PoolStats { ... } }

agent.dispatch(options, handler): boolean

Routes the request to the dispatcher for options.origin, creating one through the factory if needed. Throws an <InvalidArgumentError> when options.origin is not a non-empty string or <URL>, and a <MaxOriginsReachedError> when a new origin would exceed maxOrigins. Implements Dispatcher.dispatch().

agent.close(callback?): Promise | void

Gracefully closes the agent and every dispatcher it owns, waiting for in-flight requests to complete. Implements Dispatcher.close().

agent.destroy(error?, callback?): Promise | void

Forcefully destroys the agent and every dispatcher it owns, aborting all pending requests. Implements Dispatcher.destroy().

agent.connect(options, callback?): void

See Dispatcher.connect(). The request is routed to the dispatcher for options.origin.

agent.pipeline(options, handler): void

See Dispatcher.pipeline(). The request is routed to the dispatcher for options.origin.

agent.request(options, callback?): void

See Dispatcher.request(). The request is routed to the dispatcher for options.origin.

import { Agent } from 'undici'

const agent = new Agent()
const { statusCode, body } = await agent.request({
  origin: 'http://localhost:3000',
  path: '/',
  method: 'GET',
})

console.log('response received', statusCode)
console.log('data', await body.text())

agent.stream(options, factory, callback?): void

See Dispatcher.stream(). The request is routed to the dispatcher for options.origin.

agent.upgrade(options, callback?): void

See Dispatcher.upgrade(). The request is routed to the dispatcher for options.origin.

Emitted when a socket has been created for an origin and is ready to receive requests. Forwarded from the underlying dispatcher's 'connect' event.

Emitted when a socket for an origin has disconnected. Forwarded from the underlying dispatcher's 'disconnect' event.

Emitted when a connection attempt for an origin fails. Forwarded from the underlying dispatcher's 'connectionError' event.

Emitted when an origin's dispatcher is no longer busy and can accept more requests. Forwarded from the underlying dispatcher's 'drain' event.