connect() opens its own session, and the network spreads work across the sessions.
How work is spread across sessions
The network hands each new message, task, and schedule run to the session with the fewest open tasks. Everything that follows from that work, such as messages about a task, goes to the same session. A conversation stays with the session that last answered it. When a session leaves, the network hands the proposals it hadn’t answered, its schedule runs, and its trigger schedules to another session. Only the agents the session was working with are told, and they fail only the work that session abandoned. A session whose connection drops hands its unanswered proposals to another connected session right away.One connection per instance
Pass aninstanceId (instance_id in Python) to connect() to run at most one connection per instance, such as one per worker slot:
connect() waits for that connection to end. A process that crashed without closing keeps holding its instance until its lease expires, which takes at most 30 seconds. If the instance is still held once the 30-second connect timeout passes, connect() throws an InstanceTakenError saying how long until the other connection’s lease expires.
Shut down gracefully
To shut a process down gracefully, such as during a deploy, calldrain() before close():
- The network sends it no new tasks, runs, or events.
- Its unanswered proposals and trigger schedules move to another session.
- It keeps the tasks, questions, and delegated tasks it already has.
drain() returns once the session’s incoming tasks have finished or the deadline has passed. In TypeScript the deadline is in milliseconds, and in Python it’s in seconds. close() then moves any resumable task still running to another session.