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

# constructor()

> **new Agent**\<`E`, `State`>(`ctx`, `env`, `options?`): [`Agent`](/docs/agent-sdk/runtime-sdk)\<`E`, `State`>

Called by the runtime on every activation — never construct an agent
yourself. Re-arms the task scheduler to the earliest pending task (inside
`ctx.blockConcurrencyWhile`), so persistent timers resume after a crash or
restart. A subclass constructor must call `super(ctx, env)` first.

`options` is where a subclass configures the pieces the folded surface
builds on its behalf — event retention and the connection engine's attach
window (see [AgentOptions](/docs/agent-sdk/interface/constructor#agentoptions)). Declare a constructor and forward a
literal to `super`; the runtime keeps calling your class with `(ctx, env)`
and the values are read here, once, and never re-read.

```ts theme={null}
constructor(ctx: ActorContext, env: Env) {
  super(ctx, env, { events: { retain: 5000 } });
}
```

**Parameters**

| Parameter | Type | Description |
| - | - | - |
| `ctx` | [`ActorContext`](/docs/edge-compute/stateful-actors/api-reference/context) | The actor context supplied by the runtime. |
| `env` | `E` | The bindings supplied by the runtime. |
| `options` | [`AgentOptions`](/docs/agent-sdk/interface/constructor#agentoptions) | Optional configuration for the persistent event log and the built-in connection engine. |

**Returns**

[`Agent`](/docs/agent-sdk/runtime-sdk)\<`E`, `State`>

**Overrides**

`StatefulActor<E>.constructor`

## Type Parameters

| Parameter | Constraint | Default | Meaning |
| - | - | - | - |
| `E` | `extends Env` | `Env` | The bindings, typed as `this.env`. |
| `State` | `extends Record<string, unknown>` | `Record<string, unknown>` | The shape of the persistent state. |

## AgentOptions

Construction-time configuration for an agent's persistent event log and its
built-in connection engine.

The folded connection surface builds both for you, which leaves nothing to
configure at the call site — so an agent that needs different retention or a
different attach window declares a constructor and forwards an
`AgentOptions` literal to `super`:

```ts theme={null}
export class ResearchAgent extends Agent<Env, ResearchState> {
  constructor(ctx: ActorContext, env: Env) {
    super(ctx, env, { events: { retain: 5000 }, attachGraceMs: 1000 });
  }
}
```

The values are read once, during construction, and never re-read — the
object you pass is not retained.

**Properties**

**attachGraceMs?**

> `optional` **attachGraceMs?**: `number`

How long (ms) the connection engine waits for a client's first frame
before admitting the connection as an anonymous reader. Clients that never
attach send nothing until the bootstrap completes, so this is the latency
such a client pays on connect — and, on a policy that rejects anonymous
connections, the window a slow client must attach within. Omitted, the
engine uses its own default (300). The window starts when `webSocket`
returns; it is a timer, not a pause inside the handler.

***

**events?**

> `optional` **events?**: [`EventLogOptions`](/docs/agent-sdk/interface/events#eventlogoptions)

Retention for `this.events`, the agent's persistent progress-event stream —
see [EventLogOptions](/docs/agent-sdk/interface/events#eventlogoptions). Omitted, the log keeps its default 1000 rows.