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

# Agent Class

> The Agent base class — type parameters, construction, override hooks, and what's reserved.

`Agent<E, State>` extends `StatefulActor<E>`. Subclass it, declare async methods for
your inbound surface, and use the protected members inside them.

```ts theme={null}
import { Agent } from "@telnyx/edge-runtime";

interface MyState extends Record<string, unknown> {
  status: "idle" | "processing";
}

export class SupportAgent extends Agent<MyEnv, MyState> {
  protected override initialState(): MyState {
    return { status: "idle" };
  }

  async receive(text: string): Promise<void> {
    await this.messages.add("user", text);
    await this.queue("process");
  }
}
```

## Type parameters

| Parameter | Constraint                        | Default                   | Meaning                                             |
| --------- | --------------------------------- | ------------------------- | --------------------------------------------------- |
| `E`       | `extends Env`                     | `Env`                     | Your environment/bindings type — becomes `this.env` |
| `State`   | `extends Record<string, unknown>` | `Record<string, unknown>` | Your durable state shape                            |

## Construction

You don't construct agents yourself — the runtime does. On every activation the base
constructor also **re-arms the task scheduler** to the earliest pending task (inside
`ctx.blockConcurrencyWhile`), which is what makes timers survive crashes and restarts.

If you need your own one-shot init, override the constructor and call
`super(ctx, env)` first, exactly as with a
[StatefulActor](/docs/edge-compute/stateful-actors/api-reference/base).

## Properties

| Property        | Type         | Description                                                                             |
| --------------- | ------------ | --------------------------------------------------------------------------------------- |
| `this.messages` | `MessageLog` | The conversation history — see [Message Log](/docs/agent-sdk/api-reference/message-log) |

Plus everything inherited: `this.ctx`, `this.env`.

## Methods

State and scheduling methods are listed with full semantics on their own pages:

| Method                                       | Returns                 | Reference                                              |
| -------------------------------------------- | ----------------------- | ------------------------------------------------------ |
| `getState()`                                 | `Promise<State>`        | [State](/docs/agent-sdk/api-reference/state)           |
| `setState(patch)`                            | `Promise<State>`        | [State](/docs/agent-sdk/api-reference/state)           |
| `replaceState(next)`                         | `Promise<State>`        | [State](/docs/agent-sdk/api-reference/state)           |
| `queue(method, payload?, opts?)`             | `Promise<string>`       | [Scheduling](/docs/agent-sdk/api-reference/scheduling) |
| `schedule(seconds, method, payload?, opts?)` | `Promise<string>`       | [Scheduling](/docs/agent-sdk/api-reference/scheduling) |
| `every(seconds, method, payload?, opts?)`    | `Promise<string>`       | [Scheduling](/docs/agent-sdk/api-reference/scheduling) |
| `cancelSchedule(id)`                         | `Promise<boolean>`      | [Scheduling](/docs/agent-sdk/api-reference/scheduling) |
| `listSchedules()`                            | `Promise<TaskRecord[]>` | [Scheduling](/docs/agent-sdk/api-reference/scheduling) |

## Override hooks

| Hook                         | Fires                                                                                                          |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `initialState(): State`      | When state is read and nothing has been stored yet — return the default for a fresh actor                      |
| `onStateChanged(next, prev)` | After every `setState()` **and `replaceState()`** resolves, with the new state and the state before the change |
| `onTask(name, payload, ctx)` | When a due task's `name` matches no method on the class — `ctx.attempt` carries the delivery attempt           |
| `onConnect(conn)`            | When a client connects *(the connection layer is coming next — see [Limits](/docs/agent-sdk/limits))*          |
| `now(): number`              | Time source for the scheduler (defaults to `Date.now()`) — override in tests for a deterministic clock         |

## Reserved: `alarm()`

The SDK claims the actor's alarm slot to drive the task scheduler: when the alarm
fires, `Agent.alarm()` drains every due task, dispatches each to the method it names,
and re-arms to the next deadline. **Overriding `alarm()` in an `Agent` subclass breaks
`queue`/`schedule`/`every`.** If you need timed work, schedule a task.