# Hosted agents and the room request

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

Source: https://docs.vlayers.ai/developers/sdks/reference/hosting

Kind: Reference

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](https://docs.vlayers.ai/developers/sdks/hosting).

### serveRoom

function · `import { serveRoom } from '@voicelayer/sdk'`

```ts
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

```ts
const server = await serveRoom(agent, {
  onRequest: async (req) => ({ status: 200, body: { path: req.path } }),
});
```

### isRoomEnvironment

function · `import { isRoomEnvironment } from '@voicelayer/sdk'`

```ts
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

| 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 · `import { ServeRoomOptions } from '@voicelayer/sdk'`

```ts
interface ServeRoomOptions
```

Options 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 · `import { RoomRequest } from '@voicelayer/sdk'`

```ts
interface RoomRequest
```

A 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

```ts
json(): unknown
```

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

##### Returns

`unknown`

#### platform

```ts
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_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

```ts
await req.platform('store.put', { collection: 'notes', id: 'n1', value: { text: 'hello' } });
```

### RoomResponse

interface · `import { RoomResponse } from '@voicelayer/sdk'`

```ts
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

| 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 · `import { RoomServer } from '@voicelayer/sdk'`

```ts
interface RoomServer
```

A 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

```ts
stop(): Promise<void>
```

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

##### Returns

`Promise<void>`
