> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# new AgentClient()

> **new AgentClient**\<`TStub`, `TState`>(`url`, `opts?`): [`AgentClient`](/docs/agent-sdk/client-sdk/constructor)\<`TStub`, `TState`>

Create a client and start connecting immediately.

**Parameters**

| Parameter | Type | Description |
| - | - | - |
| `url` | `string` | The agent's WebSocket endpoint (`wss://...` or `ws://...`). |
| `opts` | [`AgentClientOptions`](/docs/agent-sdk/client-sdk/constructor#agentclientoptions) | Connection, heartbeat, and attach-mode options. |

**Returns**

[`AgentClient`](/docs/agent-sdk/client-sdk/constructor)\<`TStub`, `TState`>

**Throws**

If no global `WebSocket` exists and none was injected via
`opts.WebSocketCtor`.

## Type Parameters

| Parameter | Constraint | Default | Meaning |
| - | - | - | - |
| `TStub` | `extends Record<string, (...args: any[]) => Promise<any>>` | None | The agent's remote-callable methods, typed as `stub`. |
| `TState` | None | None | The shape of the agent's state, as `onState` listeners receive it. |

## The Address

The `url` is the address of one instance. [`mountAgents`](/docs/agent-sdk/mounting-agents) serves every instance it mounts at an address of this shape.

```text theme={null}
wss://<host>/agents/<mount>/<name>
```

* `/agents` is the mount's default base path.
* `<mount>` is a key of the mount map.
* `<name>` is the instance's routing name.

Behind a hand-written front door, the address is the one that front door serves.

## Attach Mode

Attach mode opens every connection, reconnects included, with an `attach` frame. The frame carries the token, the requested streams and, with `resume`, the cursors. The server answers with the granted claims and the accepted streams. [`claims`](/docs/agent-sdk/client-sdk/claims) holds the claims.

Without `token`, `subscribe` or `resume`, the client speaks the plain protocol. Each connection opens with snapshots of the state and the messages, followed by `hello`. The plain protocol works with servers that speak nothing else.

## Reconnects

The client reconnects on its own whenever the link drops. Only [`close`](/docs/agent-sdk/client-sdk/close) stops it. A heartbeat detects a link that died without closing. The client replaces such a link as it does a dropped one. The backoff and heartbeat options in [AgentClientOptions](#agentclientoptions) set the timing.

## AgentClientOptions

Options for [AgentClient](/docs/agent-sdk/client-sdk/constructor).

Setting any of `token` / `subscribe` / `resume` switches the client into
attach mode (see the [AgentClient](/docs/agent-sdk/client-sdk/constructor) class docs); the connection and
heartbeat options apply in both modes.

**Properties**

**pingIntervalMs?**

> `optional` **pingIntervalMs?**: `number`

Heartbeat: send a `ping` every `pingIntervalMs` (default 30\_000).

***

**pingTimeoutMs?**

> `optional` **pingTimeoutMs?**: `number`

Reconnect if a `ping` goes unanswered for `pingTimeoutMs` (default 10\_000).

***

**reconnectBackoffMs?**

> `optional` **reconnectBackoffMs?**: `number`

Base reconnect backoff in ms. Delays grow exponentially (factor 2, ±20%
jitter) from this base up to `reconnectMaxBackoffMs`.

**Default Value**

```ts theme={null}
250
```

***

**reconnectMaxBackoffMs?**

> `optional` **reconnectMaxBackoffMs?**: `number`

Upper bound on the reconnect backoff delay, in ms.

**Default Value**

```ts theme={null}
30_000
```

***

**resume?**

> `optional` **resume?**: `boolean`

Resume across reconnects: re-attach with the last-seen `messages`/`events`
cursors so the server replays exactly what was missed — no full
re-snapshot, no duplicates. The first connection carries no cursors (a
normal snapshot bootstrap is expected).

***

**subscribe?**

> `optional` **subscribe?**: readonly [`Stream`](/docs/agent-sdk/client-sdk/constructor#stream)\[]

Streams to subscribe to. Omitted = the server's default set.

***

**token?**

> `optional` **token?**: `string`

Opaque credential presented in the `attach` frame; the server derives this connection's grants from it.

***

**WebSocketCtor?**

> `optional` **WebSocketCtor?**: `AgentWebSocketCtor`

WebSocket constructor (defaults to the platform `globalThis.WebSocket`).
Inject one for environments without a global, or for tests.

## Stream

> **Stream** = `"state"` | `"messages"` | `"events"`

The pushable streams a v2 client can subscribe to.