Runtime API

The Agent SDK’s server-side surface ships in @telnyx/edge-runtime; the client SDK ships at @telnyx/edge-runtime/client with no server dependencies.

import { Agent, rpc } from "@telnyx/edge-runtime";
import { AgentSocketServer } from "@telnyx/edge-runtime/agent-socket";
import { AgentClient } from "@telnyx/edge-runtime/client";

The surface at a glance

Server side — everything here runs inside your Agent subclass.

`Agent<E, State>`

The base class. Subclass it, declare async methods for your inbound surface, and use the protected members from your own code — one page per member group:

Group	Members
Lifecycle	`constructor` · `ctx` · `env` · `fetch()` · `webSocket()` · `onConnect()` · `alarm()` (reserved)
Connection	`authorize()` · `onAttach()` · `attachments` — types `Claim`, `Attachment`, `AgentAttachments`; error `AgentSocketsNotEnabledError`
State	`getState()` · `setState()` · `replaceState()` · `initialState()` · `onStateChanged()`
Scheduling	`queue()` · `schedule()` · `every()` · `cancelSchedule()` · `listSchedules()` · `onTask()` · `now()` — types `ScheduleOptions`, `TaskRecord`
Messages	`this.messages` — an instance of the `MessageLog` class below

The agent’s persistent conversation history, accessed as this.messages. add() · append() · appendMany() · all() · last() · count() · toOpenAI() · toAnthropic() · toLangChain() — types AgentMessage, StoredMessage, ToolCall

`EventLog`

A persistent, replayable progress-event stream with cursor reads and count-based retention, accessed as this.events (or constructed standalone). constructor · emit() · read() · count() — types StoredEvent, EventLogOptions

`rpc()` / `rpcSurface()`

Standalone functions, not Agent members: @rpc() opts a method onto the remote-callable surface, and rpcSurface() introspects what a class exposes. Type RpcOptions.

`AgentSocketServer<TState>`

The server half of the agent socket protocol — construct one inside your subclass (from @telnyx/edge-runtime/agent-socket) and delegate webSocket() to it. attach() · broadcastPatch() · broadcastSnapshot() · broadcastMessages() · broadcastEvent() · watcherCount · close() · handleCall() · authorizeEnabled — types AgentSocketServerOptions, AgentServerSocket, AgentConnectContext, HandleCallOptions, HandleCallResult

`AgentHttpServer<TState>`

The HTTP front door for an AgentSocketServer (from @telnyx/edge-runtime/agent-http): the agent’s streams over Server-Sent Events, its RPC surface over POST — same frames and policy as the WebSocket path, no SDK needed on the page. fetch() · handleRpc() · handleSse() The SSE half does not stream on deployed functions yet — the edge gateway buffers the response, so use the WebSocket path in production. See AgentHttpServer for the full caveat.

`mountAgents()`

The front door (SDK ≥ 0.12.0), from @telnyx/edge-runtime/mount: one call routes every agent a function serves, giving each <base>/<mount>/<name> — the /agents/conversation/alice shape the AgentClient examples connect to — with the request’s shape selecting WebSocket, SSE, or RPC. Export it as export default { fetch: mountAgents(...) }; a bare-function default export is refused at load time. mountAgents() · encodeAgentName() · decodeAgentName() · MAX_AGENT_NAME_LENGTH — types AgentMountMap, MountOptions, MountRoute, MountCorsOptions, MountAuthorizeResult, MountHeadersInit, MountTransport Its authorize composes with the agent’s own: the mount stamps identity before any actor wakes, the caller’s credential rides through untouched, and the agent still resolves its claims. Start at Mounting Agents. Client side — the one export that runs outside the agent:

`AgentClient<TStub, TState>`

The browser/Node client (from @telnyx/edge-runtime/client, no server dependencies): connects over WebSocket, mirrors the agent’s state, and makes typed RPC calls through stub. stub · claims · onState() · onMessages() · onEvents() · isConnected() · close() — types AgentClientOptions, AgentEvent, Stream The URL it connects to is the one mountAgents serves.

Rules that apply across the whole surface

Every Agent member is protected — this is an inside-the-class API, called from your own methods. It is not part of the RPC surface your subclass exposes to stubs.

The remote surface is opt-in (SDK ≥ 0.10.0) — methods callable by connected clients over the agent socket must be decorated with @rpc(); undecorated methods answer method_private on the wire while remaining callable in-process:

import { Agent, rpc } from "@telnyx/edge-runtime";

export class Support extends Agent {
  @rpc({ description: "Human takes over the thread" })
  async humanReply(text: string) { /* callable by clients */ }

  async recalc() { /* in-process only */ }
}

alarm() is claimed by the SDK. The task scheduler runs on the actor’s single alarm slot. Do not override alarm() in an Agent subclass — schedule a task instead. (On a plain StatefulActor, alarm() remains yours — see Alarms.)

Everything from StatefulActor is still there — this.ctx, this.env, RPC dispatch, fetch() — see the StatefulActor Runtime API. Budgets and retry behavior live in Limits.

Get Started

Concepts

Build

Examples

Reference

For AI Agents

The surface at a glance

`Agent<E, State>`

`MessageLog`

`EventLog`

`rpc()` / `rpcSurface()`

`AgentSocketServer<TState>`

`AgentHttpServer<TState>`

`mountAgents()`

`AgentClient<TStub, TState>`

Rules that apply across the whole surface

​The surface at a glance

​Rules that apply across the whole surface

The surface at a glance

Rules that apply across the whole surface