Reference

Hosted agents and the room request

Reference for serveRoom, the options of a hosted agent's server, and the request its published endpoints receive.

A hosted agent runs on VoiceLayer. agent.start() detects the hosted room and serves it for you; serveRoom is the same thing called directly. Requests to your published endpoints reach onRequest as a RoomRequest, whose platform method asks the platform to act for that request.

Import from @voicelayer/sdk. For a walk-through, see Hosted agents.

serveRoom

function · @voicelayer/sdk

serveRoom(agent: AgentHandle, opts?: ServeRoomOptions): Promise<RoomServer>

Serve an agent's handlers on the hosted room's local contract: /healthz, tool calls and call start and end, with the handler context bridged to the room's platform port. .start() calls this for you inside a room. Called twice for the same agent it returns the first server.

Parameters
NameTypeRequiredDescription
agentAgentHandleyesThe agent to serve.
optsServeRoomOptionsnoPorts, the onRequest handler for published endpoints, logging and shutdown behaviour.
Returns

Promise<RoomServer>: The running server.

Throws
  • Error when the agent's definition has errors.
Example
const server = await serveRoom(agent, {
  onRequest: async (req) => ({ status: 200, body: { path: req.path } }),
});

isRoomEnvironment

function · @voicelayer/sdk

isRoomEnvironment(env?: Readonly<Record<string, string | undefined>>): boolean

Whether this process runs inside a hosted room, which the platform marks by setting VL_SHIM_PORT.

Parameters
NameTypeRequiredDefaultDescription
envReadonly<Record<string, string | undefined>>noprocess.envThe environment to read.
Returns

boolean: True inside a hosted room.

ServeRoomOptions

interface · @voicelayer/sdk

interface ServeRoomOptions

Options for serving a hosted agent. The defaults match the hosted environment, so you rarely set any.

Fields

NameTypeRequiredDescription
portnumbernoThe handlers' port ($PORT, 8080 by default).
shimPortnumbernoThe shim's actions port ($VL_SHIM_PORT, 7070 by default).
publicPortnumbernoWhere published requests arrive ($PUBLIC_PORT). Not listened on when unset (the controller sets it only for an agent with endpoints).
hoststringnoThe address to listen on. Default 0.0.0.0: the shim reaches the process over the room's loopback, and voicelayer image test over a docker network.
onRequest(req: RoomRequest) => RoomResponse | unknown | Promise<RoomResponse | unknown>noAnswers published endpoint requests. Without it, they get a 404 that says the agent has no handler.
logRunnerLoggernoWhere the server writes its log lines: an object with debug, info, warn and error functions that take a message and fields.
signalsbooleannoInstall SIGTERM/SIGINT handlers: stop accepting, finish what is running (up to drainMs), exit. Default true.
exitbooleannoExit the process when the server stops after a signal. Default true.
drainMsnumbernoHow long to let running requests finish after a stop signal, in milliseconds.
envReadonly<Record<string, string | undefined>>noThe environment to read PORT, VL_SHIM_PORT, PUBLIC_PORT and VL_ROOM_ID from. Default process.env.
fetchtypeof fetchnoThe fetch that reaches the shim. Default the global one.

RoomRequest

interface · @voicelayer/sdk

interface RoomRequest

A request to one of the hosted agent's published endpoints, as the platform authenticated it. Handed to onRequest.

Fields

NameTypeRequiredDescription
methodstringyesThe HTTP method.
pathstringyesThe path the caller used, less /<id>/<kind>.
queryURLSearchParamsyesThe query string parameters.
headersIncomingMessage['headers']yesThe request headers.
bodyBufferyesThe raw request body.
callerstring | undefinedyesWho called, as the building authenticated them (x-vl-caller).
endpointstring | undefinedyesThe endpoint's name in the manifest (x-vl-endpoint).
requestIdstring | undefinedyesThe request's id (x-vl-scope): the scope of every platform action it takes.

json

json(): unknown

The body parsed as JSON (undefined when empty or not JSON).

Returns

unknown

platform

platform(kind: PlatformActionKind, params: Record<string, unknown>): Promise<unknown>

Ask the platform to act for this request. It runs only if the endpoint lists the kind in capabilities, and it goes through the same checks as the REST API. The result is the REST route's JSON body. The kinds are calls.create, messages.send, memory.read, memory.write, conversations.read, store.get, store.put, store.query and store.delete.

Parameters
NameTypeRequiredDescription
kindPlatformActionKindyesThe action to run. One of calls.create, messages.send, memory.read, memory.write, conversations.read, store.get, store.put, store.query, store.delete.
paramsRecord<string, unknown>yesThe action's parameters, for example { collection, id, value } for store.put.
Returns

Promise<unknown>: The action's result.

Throws
  • HandlerContextError when the platform refuses: guard_denied for a blocked send, capacity for money or rate limits, not_authorized for a missing capability, invalid_args for a bad request or a missing document, handler_error for a server fault.
Example
await req.platform('store.put', { collection: 'notes', id: 'n1', value: { text: 'hello' } });

RoomResponse

interface · @voicelayer/sdk

interface RoomResponse

What onRequest may return instead of a plain value: the status, headers and body to send. A plain value is sent as JSON with status 200.

Fields

NameTypeRequiredDefaultDescription
statusnumberno200The HTTP status.
headersReadonly<Record<string, string>>noResponse headers.
bodystring | Uint8Array | unknownnoThe response body: a string, bytes, or a value sent as JSON.

RoomServer

interface · @voicelayer/sdk

interface RoomServer

A running hosted-agent server, returned by serveRoom and by .start() inside a hosted room.

Fields

NameTypeRequiredDescription
portnumberyesThe port the handlers answer on (resolved when port: 0).
publicPortnumber | undefinedyesThe port published endpoint requests arrive on, or undefined when the agent has no published endpoints.
roomIdstring | undefinedyesThe room's id ($VL_ROOM_ID), when the platform set it.
donePromise<void>yesResolves when the server has stopped.

stop

stop(): Promise<void>

Stop accepting new requests and wait for the running ones (up to drainMs).

Returns

Promise<void>