AgentHttpServer

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 does not stream on deployed functions today. The edge gateway buffers a response until it completes before returning it, so an open-ended text/event-stream never reaches the client — an EventSource against a deployed agent connects and then receives nothing. The RPC path over POST is unaffected, and SSE works normally in local development.Use the WebSocket path in production: it carries the same frames under the same authorize / onAttach policy, and mountAgents serves it on the same address, so the change is new WebSocket(url) in place of new EventSource(url) (or AgentClient, which does the reconnect and resume for you). This is a platform-side gap, tracked as COMPUTE-819; the SSE surface documented here stays and starts streaming once the gateway allows it.

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 wires this up for you: a mounted agent’s GET and POST requests are handed to its fetch, where an AgentHttpServer over the agent’s connection engine answers them on /agents/<mount>/<name> — no routing code of your 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.

Get Started

Concepts

Build

Examples

Reference

For AI Agents

AgentHttpServer

fetch()

handleRpc()

handleSse()

​fetch()

​handleRpc()

​handleSse()

fetch()

handleRpc()

handleSse()