Mounting Agents

An agent is only reachable through an Edge Compute function. Before mountAgents, every project wrote the function’s front door by hand, and each copy differed a little.

It parsed the URL and checked for an upgrade.
It pulled the credential and encoded the name.
It picked the binding and called idFromName(...).fetch(req).
It answered health checks.

mountAgents (SDK ≥ 0.12.0) is that front door, already written. The user supplies the routing table and the policy, and the mount supplies the rest.

import { mountAgents } from "@telnyx/edge-runtime/mount";
import type { ActorNamespace } from "@telnyx/edge-runtime";

interface Env {
  CONVERSATION: ActorNamespace;
  BILLING: ActorNamespace;
}

export default {
  fetch: mountAgents<Env>((env) => ({
    conversation: env.CONVERSATION,
    billing: env.BILLING,
  })),
};

fetch: is not optional. mountAgents returns a handler, and a function entry must default-export an object carrying that handler on fetch. Writing export default mountAgents(map) produces a bundle the runtime refuses at load time — the deploy does not start, so there is no request to debug.

The map is the entire routing table. Nothing is discovered, and no name is derived from a class name: an agent is reachable once it is written there, and an unknown mount key is a 404 with no binding consulted. It is a function of env, so bindings resolve per request and nothing is cached between them. Each value is an actor binding, an ActorNamespace. An [[actors]] block in telnyx.toml declares it, as the Stateful Actors configuration reference shows.

One Address, Three Transports

Each mounted agent answers on <base>/<mount>/<name>:

<base> is the path prefix the mount owns, /agents unless the option sets another, base.
<mount> is a key of the map above.
<name> is the routing name of one instance — one agent, one persistent identity.

So the function above serves /agents/conversation/alice and /agents/billing/acct-1004. Each name reaches one actor instance, the same one on every request. The first request brings it up, as Lifecycle & Placement describes. The shape of the request selects the transport, not the path. The same address answers all three:

The client sends	Address	It gets
`Upgrade: websocket`	`/agents/conversation/alice`	the agent socket protocol
`GET`	`/agents/conversation/alice?subscribe=state`	Server-Sent Events
`POST`	`/agents/conversation/alice/rpc/humanReply`	one RPC call

This is why the AgentClient reference connects to wss://my-func.telnyxcompute.com/agents/conversation/alice — that URL is the default base, the conversation mount key, and the name alice. A browser talking to the function above needs no route of its own:

import { AgentClient } from "@telnyx/edge-runtime/client";

const agent = new AgentClient<DeskStub, DeskState>(
  "wss://my-func.telnyxcompute.com/agents/conversation/alice",
  { token: sessionToken, subscribe: ["state", "messages"], resume: true },
);
agent.onState(render);
await agent.stub.humanReply("On it.");

An RPC call from a page with no SDK at all is the same address with a method on the end:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '["On it."]' \
  https://my-func.telnyxcompute.com/agents/conversation/alice/rpc/humanReply

The request body is the argument list, and the response is the same result / error frame a WebSocket caller would receive. Only methods decorated with @rpc() are callable.

SSE arrives in batches on deployed functions. A streamed response cannot cross the actor boundary, so each SSE response carries the frames ready when the agent answers. The EventSource reconnects about once a second and resumes from Last-Event-ID. The WebSocket and RPC paths are 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 policy on the same address, so the change is new WebSocket(url) in place of new EventSource(url), or AgentClient, which reconnects and resumes on its own. The full detail is on the AgentHttpServer page.

Authorization Composes — It Does Not Replace

The mount adds no policy of its own. It routes, and it runs the one authorize callback it is given. That callback does not stand in for the agent’s own authorize(token, req): both run, and they do different jobs. Gate one, at the edge. authorize(req, route) runs after the address resolves and before anything touches an actor, on every transport — an upgrade, an SSE stream, and each RPC POST alike. It receives the request unmodified and the resolved route: the mount key, the decoded name, the actor id, the transport, and the method for an RPC. Answer with a Response to reject (nothing is forwarded, no actor wakes), with headers to admit and stamp, or with nothing to admit as-is. Gate two, inside the agent. The caller’s credential rides through untouched — ?token= or an Authorization header, exactly as sent. The agent’s authorize resolves this connection’s claims from it exactly as it would with no mount in front, and onAttach may still veto.

// The function: who is this, and may they address this agent at all?
export default {
  fetch: mountAgents<Env>((env) => ({ conversation: env.CONVERSATION }), {
    authorize: async (req, { name }) => {
      const user = await verify(req.headers.get("authorization"));
      if (!user) return new Response("unauthorized", { status: 401 });
      if (user.deskId !== name) return new Response("forbidden", { status: 403 });
      return { "x-desk-user": user.id, "x-desk-role": user.role };
    },
  }),
};

// The agent: given the credential, what may this connection DO?
import { Agent, type Claim } from "@telnyx/edge-runtime";

export class Conversation extends Agent<Env, DeskState> {
  protected override authorize(token: string | undefined): readonly Claim[] {
    if (token === undefined) return ["read"];        // anonymous watcher
    return isOperator(token) ? ["read", "rpc"] : ["read"];
  }
}

Identity at the mount, grants in the agent. Two rules make the stamped identity safe to trust:

A stamped header overwrites any header of the same name the caller sent, so a client cannot forge an identity the agent trusts.
Headers the mount does not stamp are forwarded as the caller sent them. The agent trusts only what the mount stamps.

A throw from the mount’s authorize is not an admission — it propagates and the request never reaches an actor. Reading the body is safe: the agent is handed an independent copy, so a signature verified here still arrives there intact. That copy is made only for a request that carries a body, and it does buffer while both copies are outstanding — on a large streamed upload, prefer deciding from the headers.

Names Customers Already Use

Actor ids are not free-form: only ASCII letters, digits, -, _, and . are addressable, and an id built from anything else belongs to an instance that never activates. The names an application routes on are not so confined — a phone number, an email address, a composite key, a name with accents or emoji. The mount decodes the name segment and re-encodes it with encodeAgentName, which maps any name onto the addressable set reversibly:

import { encodeAgentName, decodeAgentName } from "@telnyx/edge-runtime/mount";

encodeAgentName("alice");       // "alice"           — already addressable, unchanged
encodeAgentName("+15550100");   // ":2b:15550100"
encodeAgentName("[email protected]"); // "user:40:ex.com"

decodeAgentName(":2b:15550100"); // "+15550100"      — render an id back for a human

/agents/conversation/%2B15550100 therefore addresses the agent for +15550100, and no two names ever share an instance. Three things to keep in mind:

The mapping is part of an actor’s identity and is frozen. The id a name first resolves to is where that instance’s state and timers live. Do not re-derive the rule by hand — call encodeAgentName from any other front door that addresses the same instances, or that door points the name at a different, empty instance.
Case is significant. alice and Alice are two agents. Names meant to reach one agent are lowercased before routing.
Encode the raw name exactly once. Encoding an already-encoded name escapes its : signs and addresses something else.

How Long a Name May Be

The limit is on the actor id once URL-escaped — MAX_ESCAPED_ACTOR_ID_LENGTH, 225 characters — because the id is carried into the name of the file the instance’s persistent state is kept in, which is capped at 255 bytes. How many characters of name that allows depends on which characters they are, since an escape is longer than what it replaces:

A name of…	costs per character	one run fits
ASCII letters, digits, `-`, `_`, `.`	1	225
accented Latin, Greek, Cyrillic (2 bytes)	4	54
most CJK and symbols such as `☕` (3 bytes)	6	36
emoji and other astral characters (4 bytes)	8	27

Every separate escaped run also spends 6 on the pair of : bracketing it, so a mixed name fits less than any single row suggests. A name whose id would exceed the ceiling is refused by the mount with 400 malformed_name before any actor wakes, and encodeAgentName throws rather than handing back an unusable id.

An over-long id does not fail on first use. The instance activates, serves requests, and accepts writes; the long name is only needed when it is loaded again after being evicted from memory, and from then on the instance cannot be opened and what it stored is unreachable. Nothing about the first, healthy run of it looks wrong — which is why the limit is checked up front. See Limits and escapedActorIdLength().

What the Mount Answers Itself

Request	Answer
`/health/liveness`, `/health/readiness`	`200 ok`, no actor woken, nothing about what is mounted in the body
A path outside `base`	the `fallback`, or `404`
Unknown mount key, malformed address, empty name	`404` — one body for all of them
A name with no faithful actor id	`400`, naming the problem
A shape matching no transport — a `PUT`, a `GET` on an RPC address, an upgrade to one	`405` with an `Allow` header

No actor is woken for any of them. Refusals from the mount carry a JSON body with an error of not_found, method_not_allowed, or malformed_name; answers from the agent — including its own errors — are relayed unchanged. Set health: false when the surrounding function owns its own health routes.

Composing with Other Routes

A mount does not have to own the whole function. fallback receives every request whose path is not under base, so the function’s own handler keeps its routes and the agent addresses never reach it:

export default {
  fetch: mountAgents<Env>((env) => ({ conversation: env.CONVERSATION }), {
    base: "/agents",          // the paths the mount owns
    fallback: myRouter.fetch, // every other path
    health: false,            // the function answers its own health checks
  }),
};

Cross-origin Browsers

Absent cors, the mount sends no CORS headers and answers OPTIONS with 405, so a page from another origin cannot reach it. Opt in when a browser page served elsewhere must open an EventSource or fetch an RPC address:

{
  cors: {
    origin: ["https://desk.example.com"],
    credentials: true, // requires a concrete origin — never "*"
  },
}

It is a passthrough and nothing more: it does not authenticate, and it never substitutes for authorize. Mount names are ordinary path segments, not secrets — they are part of the address every legitimate client already knows.

mountAgents reference — every option, type, and refusal in full
AgentClient — the browser/Node client that connects to the address above
AgentSocketServer and AgentHttpServer — what answers on the agent side of each transport
webSocket() — the entry a class overrides to own its sockets

Get Started

Inside the Managed Harness

The Agent Harness SDK

The Agent Runtime SDK

The Agent Client SDK

For AI Agents

Mounting Agents

One Address, Three Transports

Authorization Composes — It Does Not Replace

Names Customers Already Use

How Long a Name May Be

What the Mount Answers Itself

Composing with Other Routes

Cross-origin Browsers

Next

​One Address, Three Transports

​Authorization Composes — It Does Not Replace

​Names Customers Already Use

​How Long a Name May Be

​What the Mount Answers Itself

​Composing with Other Routes

​Cross-origin Browsers

​Next

One Address, Three Transports

Authorization Composes — It Does Not Replace

Names Customers Already Use

How Long a Name May Be

What the Mount Answers Itself

Composing with Other Routes

Cross-origin Browsers

Next