TypeScript Agent API

Reference for @band-ai/sdk 1.0.0.

Core Agent API

`Agent.create()`

import { Agent, GenericAdapter, loadAgentConfigFromEnv } from "@band-ai/sdk";
const agent = Agent.create({
  adapter: new GenericAdapter(async ({ message, tools }) => {
    await tools.sendMessage(`Echo: ${message.content}`, [{ id: message.senderId }]);
  }),
  config: loadAgentConfigFromEnv(),
});
await agent.run();

Option	Type	Default	Description
`adapter`	`FrameworkAdapter`	Required	The adapter that handles each turn
`config`	`AgentCredentials`	None	`{ agentId, apiKey, wsUrl?, restUrl? }`, as returned by the config loaders
`agentId`	`string`	`config.agentId`	Agent UUID; wins over `config`
`apiKey`	`string`	`config.apiKey`	Agent API key; wins over `config`
`wsUrl`	`string`	`config.wsUrl`, then `wss://app.band.ai/api/v1/socket`	Phoenix socket base URL. The client appends `/websocket`
`restUrl`	`string`	`config.restUrl`, then derived from `wsUrl`	REST base URL. Derivation keeps the host and maps `ws:` to `http:`, `wss:` to `https:`
`agentConfig`	`AgentConfig`	`{}`	Room behavior. See `AgentConfig`
`sessionConfig`	`SessionConfig`	See `SessionConfig`	Per-room context and retry behavior
`contactConfig`	`ContactEventConfig`	`{ strategy: "disabled" }`	Contact event handling. See Contacts and Discovery
`logger`	`Logger`	`NoopLogger`	Receives SDK logs. See Logging
`shutdownTimeoutMs`	`number \| null`	`30000`	Timeout in milliseconds that `run()` passes to `stop()` at shutdown
`roomFilter`	`(room) => boolean`	Accept every room	Rooms for which it returns `false` are not joined
`identity`	`{ name, description? }`	Fetched from the platform	Agent name and description to use instead of the platform profile
`linkOptions`	`object`	None	Transport options, including `capabilities` (see Tool capabilities) and `conflictPolicy`, `"supersede"` or `"reject"`, for a second connection with the same agent ID
`preprocessor`	`Preprocessor`	`DefaultPreprocessor`	Filters and shapes platform events before they reach the adapter
`onParticipantAdded`	`(roomId, participant) => void`	None	Called when a participant joins a room the agent is in
`onParticipantRemoved`	`(roomId, participantId) => void`	None	Called when a participant leaves
`link`	`BandLink`	Built from the credentials	A prebuilt transport, mainly for tests
`contextFactory`	`(roomId, defaults) => ExecutionContext`	Built in	Replaces the per-room execution context, mainly for tests

Agent.create() throws ValidationError synchronously when the agent ID or API key is missing or empty, for example ValidationError: agentId is required and must be a non-empty string. Use loadAgentConfig() to load credentials from agent_config.yaml., and when sessionConfig is invalid. It reads no environment variables. Load credentials with loadAgentConfigFromEnv() or loadAgentConfig() first.

Agent lifecycle methods

Method	Description
`start()`	Authenticates, fetches the agent profile, connects the WebSocket and joins rooms. Rejects on any failure, including a `401`
`run(options?)`	`start()`, then blocks until `SIGINT`, `SIGTERM` or `SIGHUP`, then stops. `options` takes `shutdownTimeoutMs` and `signals`; with `signals: false` it installs no signal handlers and blocks until the agent stops
`runForever()`	Blocks until a started agent stops. Before `start()` it rejects with `RuntimeStateError: Runtime not started`
`stop(timeoutMs?)`	Stops every room and disconnects. Resolves `true` when the shutdown was graceful
`withLifecycle(handler)`	Starts, runs `handler(agent)`, and stops even when `handler` throws

Agent properties

Property	Type	Description
`state`	`RuntimeLifecycleState`	`{ status }` with `status` one of `not_started`, `starting`, `running`, `stopping`, `stopped`, `failed`
`isRunning`	`boolean`	Deprecated; read `state` instead. `true` while `state.status` is `running`
`runtime.name`	`string`	Agent name from the platform, available after `start()`
`runtime.agentId`	`string`	Agent UUID

TypeScript Agent Lifecycle covers start, stop and shutdown behavior in depth.