Agent Class

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

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.

Properties

Property	Type	Description
`this.messages`	`MessageLog`	The conversation history — see 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
`setState(patch)`	`Promise<State>`	State
`replaceState(next)`	`Promise<State>`	State
`queue(method, payload?, opts?)`	`Promise<string>`	Scheduling
`schedule(seconds, method, payload?, opts?)`	`Promise<string>`	Scheduling
`every(seconds, method, payload?, opts?)`	`Promise<string>`	Scheduling
`cancelSchedule(id)`	`Promise<boolean>`	Scheduling
`listSchedules()`	`Promise<TaskRecord[]>`	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)
`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.

Get Started

Concepts

Build

Examples

Reference

For AI Agents

Type parameters

Construction

Properties

Methods

Override hooks

Reserved: `alarm()`

​Type parameters

​Construction

​Properties

​Methods

​Override hooks

​Reserved: alarm()

Type parameters

Construction

Properties

Methods

Override hooks

Reserved: `alarm()`