TypeScript Configuration

Reference for @band-ai/sdk 1.0.0.

Configuration

`loadAgentConfig()`

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()`

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 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.

`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

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 to join only some rooms. See the 1.0 migration note.

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