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
| Name | Type | Required | Description |
|---|---|---|---|
agent | AgentHandle | yes | The agent to serve. |
opts | ServeRoomOptions | no | Ports, 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>>): booleanWhether this process runs inside a hosted room, which the platform marks by setting VL_SHIM_PORT.
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
env | Readonly<Record<string, string | undefined>> | no | process.env | The environment to read. |
Returns
boolean: True inside a hosted room.
ServeRoomOptions
interface · @voicelayer/sdk
interface ServeRoomOptionsOptions for serving a hosted agent. The defaults match the hosted environment, so you rarely set any.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
port | number | no | The handlers' port ($PORT, 8080 by default). |
shimPort | number | no | The shim's actions port ($VL_SHIM_PORT, 7070 by default). |
publicPort | number | no | Where published requests arrive ($PUBLIC_PORT). Not listened on when unset (the controller sets it only for an agent with endpoints). |
host | string | no | The 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> | no | Answers published endpoint requests. Without it, they get a 404 that says the agent has no handler. |
log | RunnerLogger | no | Where the server writes its log lines: an object with debug, info, warn and error functions that take a message and fields. |
signals | boolean | no | Install SIGTERM/SIGINT handlers: stop accepting, finish what is running (up to drainMs), exit. Default true. |
exit | boolean | no | Exit the process when the server stops after a signal. Default true. |
drainMs | number | no | How long to let running requests finish after a stop signal, in milliseconds. |
env | Readonly<Record<string, string | undefined>> | no | The environment to read PORT, VL_SHIM_PORT, PUBLIC_PORT and VL_ROOM_ID from. Default process.env. |
fetch | typeof fetch | no | The fetch that reaches the shim. Default the global one. |
RoomRequest
interface · @voicelayer/sdk
interface RoomRequestA request to one of the hosted agent's published endpoints, as the platform authenticated it. Handed to onRequest.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
method | string | yes | The HTTP method. |
path | string | yes | The path the caller used, less /<id>/<kind>. |
query | URLSearchParams | yes | The query string parameters. |
headers | IncomingMessage['headers'] | yes | The request headers. |
body | Buffer | yes | The raw request body. |
caller | string | undefined | yes | Who called, as the building authenticated them (x-vl-caller). |
endpoint | string | undefined | yes | The endpoint's name in the manifest (x-vl-endpoint). |
requestId | string | undefined | yes | The request's id (x-vl-scope): the scope of every platform action it takes. |
json
json(): unknownThe 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
| Name | Type | Required | Description |
|---|---|---|---|
kind | PlatformActionKind | yes | The action to run. One of calls.create, messages.send, memory.read, memory.write, conversations.read, store.get, store.put, store.query, store.delete. |
params | Record<string, unknown> | yes | The 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_deniedfor a blocked send,capacityfor money or rate limits,not_authorizedfor a missing capability,invalid_argsfor a bad request or a missing document,handler_errorfor a server fault.
Example
await req.platform('store.put', { collection: 'notes', id: 'n1', value: { text: 'hello' } });RoomResponse
interface · @voicelayer/sdk
interface RoomResponseWhat 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
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
status | number | no | 200 | The HTTP status. |
headers | Readonly<Record<string, string>> | no | Response headers. | |
body | string | Uint8Array | unknown | no | The response body: a string, bytes, or a value sent as JSON. |
RoomServer
interface · @voicelayer/sdk
interface RoomServerA running hosted-agent server, returned by serveRoom and by .start() inside a hosted room.
Fields
| Name | Type | Required | Description |
|---|---|---|---|
port | number | yes | The port the handlers answer on (resolved when port: 0). |
publicPort | number | undefined | yes | The port published endpoint requests arrive on, or undefined when the agent has no published endpoints. |
roomId | string | undefined | yes | The room's id ($VL_ROOM_ID), when the platform set it. |
done | Promise<void> | yes | Resolves 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>