> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.band.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.band.ai/_mcp/server.

# TypeScript Configuration

Reference for `@band-ai/sdk` 1.0.0.

## Configuration

### `loadAgentConfig()`

```typescript
loadAgentConfig(agentKey?: string, configPath?: string): AgentConfigResult
```

Reads `configPath`, default `./agent_config.yaml`. When the file has a top-level `agentKey` section, that section supplies `agent_id`, `api_key`, and optional `ws_url` and `rest_url`; otherwise the file's top level does. Returns `{ agentId, apiKey, wsUrl?, restUrl?, ...otherKeys }`.

| Failure                         | Error                                                                                                                                         |
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| File missing                    | `ValidationError: Config file not found: ./agent_config.yaml. Copy agent_config.yaml.example to agent_config.yaml and configure your agents.` |
| `agent_id` or `api_key` missing | `ValidationError: Missing required fields in ./agent_config.yaml: agent_id, api_key`                                                          |

`loadAgentConfigs(configPath)` returns every section of a keyed file, as a record keyed by section name.

### `loadAgentConfigFromEnv()`

```typescript
loadAgentConfigFromEnv(options?: { env?: Record<string, string | undefined>; prefix?: string }): AgentCredentials
```

Reads `BAND_AGENT_ID`, `BAND_API_KEY`, `BAND_WS_URL` and `BAND_REST_URL` from `options.env`, default `process.env`, falling back per variable to the legacy `THENVOI_*` name with a one-time deprecation warning. An explicit `prefix` is used exactly, with no fallback. [Environment Variables](/sdks/typescript/configuration#environment-variables) lists the variables and errors.

### Environment Variables

`@band-ai/sdk` 1.0.0 reads configuration only through its two loaders; `Agent.create()` reads no environment variables, and nothing loads `.env`. Start the agent with Node's flag, `npx tsx --env-file=.env agent.ts`, to load one. `loadAgentConfig(agentKey?, configPath?)` reads `./agent_config.yaml` with the same keyed or flat layout, including optional `ws_url` and `rest_url` keys. `loadAgentConfigFromEnv()` reads these variables from `process.env`:

| Variable        | Required | Legacy fallback    | Default                                                                                      |
| :-------------- | :------- | :----------------- | :------------------------------------------------------------------------------------------- |
| `BAND_AGENT_ID` | Yes      | `THENVOI_AGENT_ID` | None                                                                                         |
| `BAND_API_KEY`  | Yes      | `THENVOI_API_KEY`  | None                                                                                         |
| `BAND_WS_URL`   | No       | `THENVOI_WS_URL`   | `wss://app.band.ai/api/v1/socket`; the client appends `/websocket`                           |
| `BAND_REST_URL` | No       | `THENVOI_REST_URL` | Derived from the WebSocket URL: same host, `wss:` becomes `https:` and `ws:` becomes `http:` |

Each `BAND_*` variable wins over its legacy name independently, and reading a legacy name prints a one-time warning such as `[band] THENVOI_AGENT_ID is deprecated; use BAND_AGENT_ID instead`. Missing credentials throw `ValidationError: Missing required fields in environment variables (BAND_AGENT_ID and BAND_API_KEY (legacy THENVOI_* still accepted)): agent_id, api_key. ...`. `loadAgentConfigFromEnv({ prefix: "MY_" })` reads `MY_AGENT_ID` and the other three with that exact prefix and no legacy fallback. The URL variables take effect only through `loadAgentConfigFromEnv()`; an agent configured with `loadAgentConfig()` uses the YAML keys instead. Provider keys are read by each provider's client, or passed as adapter options such as `new AnthropicAdapter({ apiKey })`. The TypeScript SDK reads no logging variables; see [Logging](/sdks/typescript/logging-errors#logging).

### `AgentConfig`

| Field                        | Type      | Default | Description                                                                                                                                                                                                                           |
| :--------------------------- | :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `autoSubscribeExistingRooms` | `boolean` | `true`  | Join the rooms the agent already belongs to at startup and after a whole-agent reconnect, subject to `roomFilter`, then catch up on their unprocessed messages. With `false`, the agent joins only rooms it is added to while it runs |

> **Note**
>
> As of `@band-ai/sdk` 1.0.0, `autoSubscribeExistingRooms` defaults to `true`, matching the Python SDK. Earlier releases defaulted to `false`. On its first 1.0 start, an agent that never set the option joins every room it already belongs to and may answer messages waiting there. Pass `agentConfig: { autoSubscribeExistingRooms: false }` to keep the earlier behavior, or keep the default and pass a [`roomFilter`](/sdks/typescript/agent#agentcreate) to join only some rooms. See the [1.0 migration note](https://github.com/band-ai/band-sdk-typescript/blob/sdk-v1.0.0/docs/migrations/1.0-rejoin-existing-rooms.md).

### `SessionConfig`

| Field                    | Type      | Default | Description                                                   |
| :----------------------- | :-------- | :------ | :------------------------------------------------------------ |
| `enableContextCache`     | `boolean` | `true`  | Cache each room's context between turns                       |
| `contextCacheTtlSeconds` | `number`  | `300`   | Cache lifetime; `0` keeps it until it is refreshed or changed |
| `maxContextMessages`     | `number`  | `100`   | Messages of history loaded per room, from `1` to `100`        |
| `maxMessageRetries`      | `number`  | `1`     | Times a failed message is retried before it is marked failed  |
| `enableContextHydration` | `boolean` | `true`  | Load room history when the room is first joined               |

As of `@band-ai/sdk` 1.0.0, `SessionConfig` also controls the room's working indicator, the signal that the agent is processing a turn:

| Field                          | Type      | Default | Description                                                                        |
| :----------------------------- | :-------- | :------ | :--------------------------------------------------------------------------------- |
| `enableWorkingState`           | `boolean` | `true`  | Report the working indicator while a turn runs                                     |
| `workingKeepAliveSeconds`      | `number`  | `3`     | Refresh interval; greater than `0` and less than `5`                               |
| `workingRequestTimeoutSeconds` | `number`  | `2`     | Timeout for each refresh; greater than `0` and less than `workingKeepAliveSeconds` |
| `maxWorkingStateSeconds`       | `number`  | Unset   | Upper bound on how long one turn reports working                                   |

`workingKeepAliveSeconds + 2 * workingRequestTimeoutSeconds` must also stay below `10`, the platform's working-state lifetime, so a keep-alive of `4.5` with a timeout of `3` is rejected. These rules apply only while `enableWorkingState` is `true`. A violation makes `Agent.create()` throw, naming the field, for example `ValidationError: Invalid sessionConfig: workingRequestTimeoutSeconds: Invalid enabled working-state timing`.