The HTTP Server

AgentHttpServer (SDK ≥ 0.11.0) is the HTTP front door for an AgentSocketServer: the agent’s streams over Server-Sent Events (GET answers a text/event-stream response), and its RPC surface over POST to …/rpc/<method>. It is a second encoder over the same server — same frames, same authorize / onAttach policy, same dispatch as the WebSocket path — so a plain page with an EventSource and fetch() needs no SDK at all.

SSE arrives in batches on deployed functions. A streamed response cannot cross the actor boundary on the deployed platform. Each SSE response carries the frames available when the handler returns, waiting up to 200 ms for the first, and ends with retry: 1000. The EventSource then reconnects and resumes from Last-Event-ID, so a deployed agent’s SSE behaves as a poll about once a second. The RPC path over POST is unaffected, and SSE streams live in local development.The WebSocket path is the live one for production. It carries the same frames under the same authorize and onAttach policy, and mountAgents serves it on the same address. The change is new WebSocket(url) in place of new EventSource(url), or AgentClient, which reconnects and resumes on its own.

Construct one over the socket server the actor’s webSocket delegates to, and route HTTP requests from the actor’s fetch into fetch():

import { Agent, type Env } from "@telnyx/edge-runtime";
import { AgentSocketServer, type AgentServerSocket } from "@telnyx/edge-runtime/agent-socket";
import { AgentHttpServer } from "@telnyx/edge-runtime/agent-http";

export class Conversation extends Agent<Env> {
  private desk = new AgentSocketServer<Record<string, unknown>>(this, {
    getState: () => this.getState(),
    getMessages: () => this.messages.all(),
    authorize: (token) => (token === "secret" ? ["read", "rpc"] : ["read"]),
  });
  private door = new AgentHttpServer(this.desk);

  async webSocket(ws: AgentServerSocket, req: Request): Promise<void> {
    await this.desk.attach(ws, req);
  }

  override fetch(req: Request): Promise<Response> {
    return this.door.fetch(req);
  }
}

On the SSE path the credential rides the token query parameter — an EventSource cannot set headers — and subscribe picks the streams (subscribe=state,messages; omitted = every stream the server offers). Each server frame becomes one SSE event, and the id: carries resume cursors so the browser’s automatic reconnect replays only what it missed. On the RPC path the credential rides Authorization: Bearer <token> (preferred) or the same query parameter; the JSON-array request body is the argument list, and the response body is the same result / error frame a WebSocket caller would receive. mountAgents hands a mounted agent’s GET and POST requests to the actor’s fetch on /agents/<mount>/<name>. The override above answers them there, and the function needs no routing code of its own. See mountAgents. Two limits, by design: SSE is one-way, so there are no server→client calls mid-stream (RPC is client-initiated POST only), and there is no ping/pong — an EventSource detects a dropped stream and reconnects by itself.

The Fetch Entry

AgentHttpServer.fetch is the body of the actor’s fetch entry. It chooses between the RPC and the stream by method and address.

// agent-client/http.ts
async fetch(req) {
  const url = new URL(req.url);
  const parsed = rpcMethodFromPath(url.pathname);
  if (parsed !== undefined) {
    // …
    if (req.method !== "POST") {
      return frameResponse(syntheticError("protocol_error", "RPC requires POST"), 405);
    }
    return this.handleRpc(req, parsed.method);
  }
  if (req.method === "GET")
    return this.handleSse(req);
  return frameResponse(syntheticError("protocol_error", `unsupported method ${req.method}`), 405);
}

fetch(req) on the actor passes the request the mount forwarded, with its URL and query string intact. Agent inherits the base fetch, which answers 404. The example above overrides it.
ActorFetchTimeoutError ends a fetch that runs past its 30-second budget. An RPC over POST runs inside that fetch and shares the budget.

Get Started

Inside the Managed Harness

The Agent Harness SDK

The Agent Runtime SDK

The Agent Client SDK

For AI Agents

The HTTP Server

The Fetch Entry

​The Fetch Entry

The Fetch Entry