mountAgents

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

interface Env {
  CONVERSATION: ActorNamespace;
}

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

​

The address, and what selects the transport

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

// mount key ─────────────────────────┐    ┌─── routing name
const agent = new AgentClient(
  "wss://my-func.telnyxcompute.com/agents/conversation/alice",
);

​

Two gates, not one

1. At the edge, before any actor wakes — authorize(req, route) sees the inbound request and what the mount resolved from it (mount, name, actorId, transport, and for RPC the method). Return a Response to reject — nothing is forwarded and no actor is woken — or return headers to stamp identity onto the request, or nothing to admit as-is. It runs identically on all three transports, so no request shape reaches an agent around it.
2. Inside the agent — the caller’s credential rides through untouched (?token=, or an Authorization header), so Agent.authorize resolves this connection’s claims from it exactly as it would unmounted, and onAttach may still veto.

export default {
  fetch: mountAgents<Env>((env) => ({ conversation: env.CONVERSATION }), {
    authorize: async (req, { mount, name }) => {
      const user = await verify(req.headers.get("authorization"));
      if (!user) return new Response("unauthorized", { status: 401 });
      if (user.id !== name) return new Response("forbidden", { status: 403 });
      return { "x-desk-user": user.id }; // stamped — overwrites any caller header
    },
  }),
};

​

mountAgents()

mountAgents<E>(map, options?): (req, env) => Promise<Response>

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

export default {
  fetch: mountAgents((env: Env) => ({ support: env.SUPPORT }), {
    authorize: async (req, { name }) => {
      const user = await verify(req);
      if (!user) return new Response("unauthorized", { status: 401 });
      return { "x-desk-user": user.id };
    },
  }),
};

• /health/liveness and /health/readiness → 200 ok, with no actor woken and nothing about what is mounted in the body (see health).
• A path outside base → fallback, or 404.
• An address the mount owns but cannot resolve — an unknown mount key, a malformed address, an empty name → 404, one body for all of them.
• A name that will not decode, one whose actor id would exceed MAX_ESCAPED_ACTOR_ID_LENGTH characters once escaped, or one with no faithful actor id → 400, with a message naming the problem.
• A request whose shape matches no transport (a PUT, a GET on an RPC address, an upgrade to an RPC address) → 405 with an Allow header. No actor is woken for any of them.

• Headers authorize stamps overwrite what the caller sent under the same name, so a stamped identity cannot be forged.
• Headers it does not stamp are forwarded as the caller sent them. Trust only what you stamp.

​

AgentMountMap

AgentMountMap<E> = (env) => Readonly<Record<string, ActorNamespace | undefined>>

mountAgents((env) => ({ support: env.SUPPORT, billing: env.BILLING }));

​

MountOptions

optional authorize?: (req, route) => MountAuthorizeResult | Promise<MountAuthorizeResult>

authorize: async (req, { mount, name }) => {
  const user = await verify(req.headers.get("authorization"));
  if (!user) return new Response("unauthorized", { status: 401 });
  return { "x-desk-user": user.id };
}

optional base?: string

optional cors?: MountCorsOptions

optional fallback?: (req, env) => Response | Promise<Response>

export default { fetch: mountAgents(map, { fallback: myRoutes }) };

optional health?: boolean

​

MountRoute

readonly actorId: string

readonly optional method?: string

readonly mount: string

readonly name: string

readonly transport: MountTransport

​

MountCorsOptions

optional credentials?: boolean

optional headers?: readonly string[]

optional maxAge?: number

unset — the browser's own default

origin: string | readonly string[]

​

MountAuthorizeResult

MountAuthorizeResult = Response | MountHeadersInit | void

• a Response — reject; no actor is woken and nothing is forwarded;
• a MountHeadersInit — admit, stamping those headers onto the forwarded request (each one overwrites any same-named header the caller sent);
• nothing — admit, stamping nothing.

​

MountHeadersInit

MountHeadersInit = Headers | Record<string, string> | [string, string][]

return { "x-desk-user": user.id };            // object literal
return [["x-desk-user", user.id]];            // entry pairs
return new Headers({ "x-desk-user": id });    // a built Headers

​

MountTransport

MountTransport = "websocket" | "sse" | "rpc"

​

Names

​

encodeAgentName()

encodeAgentName(name): string

encodeAgentName("alice");        // "alice"          (already addressable — unchanged)
encodeAgentName("case-42");      // "case-42"        (already addressable — unchanged)
encodeAgentName("v1.2.3");       // "v1.2.3"         (already addressable — unchanged)
encodeAgentName("+15550100");    // ":2b:15550100"
encodeAgentName("a/b");          // "a:2f:b"
encodeAgentName("user@ex.com");  // "user:40:ex.com"
encodeAgentName("café-☕");       // "caf:c3a9:-:e29895:"

encodeAgentName("a".repeat(225));  // 225 characters in, 225 out — the most a name can be
encodeAgentName("☕".repeat(36));   // 36 in, 218 out, 222 escaped — inside the limit
encodeAgentName("☕".repeat(37));   // throws: 228 escaped characters of id

​

decodeAgentName()

decodeAgentName(id): string

decodeAgentName("alice");              // "alice"
decodeAgentName(":2b:15550100");       // "+15550100"
decodeAgentName("user:40:ex.com");     // "user@ex.com"
decodeAgentName("caf:c3a9:-:e29895:"); // "café-☕"

​

MAX_AGENT_NAME_LENGTH

const MAX_AGENT_NAME_LENGTH: 225 = MAX_ESCAPED_ACTOR_ID_LENGTH