TypeScript Agent Lifecycle

TypeScript Lifecycle

@band-ai/sdk 1.0.0 starts and stops in this order:

Agent.create() → start()
                   ├── getAgentMe()                 name, description, feature flags; skipped when identity is set and tasks is off
                   ├── onStarted(name, description) before the WebSocket opens
                   ├── connect, subscribe agent_rooms and enabled agent_contacts
                   └── subscribe existing rooms     each room then catches up on /messages/next
                 running
                 stop(timeoutMs) → stop each room, onCleanup(roomId), disconnect, onRuntimeStop()

Method or hook	Behavior
`agent.run({ shutdownTimeoutMs, signals })`	Starts, waits, and stops on SIGINT, SIGTERM, or SIGHUP. A second signal during shutdown, or a `stop()` that rejects, exits with code 1. `signals: false` registers no handlers.
`agent.withLifecycle(handler)`	Starts, awaits `handler(agent)`, and stops in a `finally`. Registers no signal handlers.
`agent.stop(timeoutMs)`	Resolves `true` when every room finished its turn in time, `false` when the timeout cut one off. With no argument it waits without a limit. `run()` and `withLifecycle()` pass `shutdownTimeoutMs`, default `30000`.
`agent.state.status`	`"not_started"`, `"starting"`, `"running"`, `"stopping"`, `"stopped"`, or `"failed"`, with `error` on `"failed"`. A stopped or failed agent can be started again.
`onRuntimeStop()`	Optional adapter hook, called once per stop after every room has stopped. Release resources shared across rooms here.

If a startup step fails, start() tears down what it built and rejects. A stop() during start() supersedes the start, which rejects with RuntimeStateError, and a start() during stop() rejects with RuntimeStateError. The TypeScript SDK takes no single-instance lock. To have Band refuse a second connection instead of replacing the first, pass linkOptions: { conflictPolicy: "reject" } to Agent.create().

TypeScript reference.