Skip to main content
A Session identifies a continuing work context. A Run identifies one submission. An Agent template identifies reusable execution configuration. Sessions A and B can share a template while retaining independent workspaces and histories. C needs no template. Runs 1 and 2 execute sequentially in A; they cannot both be active.

Durable Session identity

A Session pins its Harness, connection configuration, and optional template revision. It associates workspace, conversation, and cloud resources. Recreating an SDK client does not change its identity; an authorized client in another language can continue using the same ID. A Session is not a cloud machine. Strategies such as Modal recreation can change the resource while preserving Session identity. Conversely, an existing Session record does not prove its original process or memory survives. Closure is terminal and cleans up cloud resources. Suspension and Provider standby are continuation strategies. Historical Runs and exported artifacts can remain after closure without guaranteeing access to the former workspace.

One traceable submission

A Run has input, idempotent request identity, state, durable events, and a result. A normal follow-up uses a new key and creates a new Run. Recovering a lost response reuses the original key to retrieve the original Run. Authorization and approval waits remain active execution. Disconnecting a stream neither releases the one-active-Run constraint nor cancels work. A disconnected UI should resume observation instead of submitting duplicate work.

Optional configuration reuse

Templates preserve immutable revisions. Revising does not overwrite existing Sessions; archiving does not close their resources. Create a new Session when a different pinned definition is needed, and explicitly transfer required inputs.

Follow two projects and three Runs

The diagram’s labels are examples, not resource IDs to paste into API calls. Imagine a reusable “project editor” template at revision 1. Session A contains the inventory project; Session B contains a documentation project. Run 1 adds inventory filtering in A. After Run 1 reaches a terminal state, Run 2 adjusts the filter labels in that same Session. Run 3 edits the documentation project in B. Sharing the template does not share project files, native conversation history or the Run list between A and B. The separate direct-configuration branch shows that the same execution model works without saving a template first. Select either a direct Harness definition or agent_id when creating a Session. A template is configuration reuse, not a continuously running Agent process, a separate cloud account or a prerequisite for the first task. Keep your business request mapping in your backend. A valid Hexagon object ID establishes which record to address; it does not prove that the current business user may access that record.

Two mistakes that create different work

“The stream disconnected, so create another Run.” Suppose Run 1 is still executing when the browser loses its connection. A new key requests new work, and the same Session rejects it with 409 session_busy while Run 1 remains active. If the original Run has already finished by the time the retry arrives, that new key can create a second task instead. Recover the original Run ID and reconnect after your persisted event cursor. If the submission response itself was lost, retry the original Session, input, origin and key. Changing input or origin while reusing the key returns 409 idempotency_conflict; origin.message_id alone is correlation metadata, not automatic deduplication. “Editing the template updates the current project.” Suppose the editor template is revised to revision 2 after Sessions A and B exist. Their historical definitions remain revision 1. A new Session can select the new revision, but it will not automatically inherit A’s workspace or conversation. Decide which files/context to transfer explicitly and create the new work context. Archiving the template prevents new creation from that archived Agent; it is not a command to cancel Runs or close Sessions already created from it.

Lifecycle decisions for an application

A free active-Run slot is not a health guarantee: an interrupted Runtime or changed connection can still prevent a follow-up. Cancellation does not itself close the Session or undo external writes. Even after closure, retrying an already accepted submission with its original matching key can return its historical Run; that is retrieval of accepted work, not reopening the Session. Sources: Sessions, submission. Next: multi-turn work, templates, recovery. Exact fields and errors: Sessions API, Runs API. Historical configuration: initialization contract.