Session

A session is a logical conversation resource selected by Agent nodes. Its persistence setting determines whether invocations share provider conversation state. Nodes that select the same persistent session share its conversation; nodes using the same profile may select independent sessions.

An agent session is distinct from the account session used to sign in to Verdog's hosted services.

Persistence and lifetime

Persistence	Behavior
Non-persistent	Every invocation starts without an earlier provider conversation.
Persistent	Later invocations resume the provider conversation established earlier in the run.

An agent session is confined to one workflow run during ordinary execution. A new run starts with new sessions unless an explicit restart or fork branches a committed persistent conversation. Once established, a persistent session retains its provider identity and access mode. A later invocation with a different provider or access mode raises AgentInvocationError; the workspace may vary between invocations.

A local session belongs to one subroutine invocation. A workflow may also own sessions and map them to entry-subroutine parameters. A subroutine call can pass an existing session through a session parameter; a workflow call creates a new workflow resource scope.

Generated interface

A local session module exports SESSION, an AgentSessionDefinition containing its ID, name, and persistent flag. A workflow-owned session uses the same declaration type in the workflow's resource scope. These declarations identify logical resources; they do not contain a provider conversation ID.

An Agent node's generated declaration selects its session ID independently of its profile ID. The runtime tracks conversation state for that bound resource as the authored visit calls context.invoke().

A successful provider invocation advances the session before the visit parses the reply or the graph commits its next transition. A later visit failure does not itself undo that conversation update.

Session parameters

A caller-supplied session slot exports SESSION_PARAMETER, an AgentSessionParameter containing its ID and name. It does not declare persistence: the supplied session owns that policy.

The module also exports RESOLVED_SESSIONS, a tuple of concrete SESSION declarations reached through session_arguments on workflow entries and subroutine calls inside the project. A call may pass a caller's local session or forward one of its own session parameters. Resolution follows forwarded parameters to their callers, using the same procedure as profile parameters.

The imported aliases begin with WORKFLOW_ or SUBROUTINE_ and include the binding definition's canonical ID and the concrete session ID. A parameter bound only by callers outside this project has an empty RESOLVED_SESSIONS tuple. This tuple supports source navigation and does not affect runtime binding.

Workflow-owned sessions are collected by the workflow's session registry.

Authored files

Sessions have no authored files. Configure persistence and resource mappings in project.json; generation maintains the Python interface. An Agent visit does not create, store, or pass provider conversation IDs itself.

Files

General session structure

sessions/
├── ◆ __init__.py
├── <local-session>/
│   └── ◆ __init__.py
└── <session-parameter>/
    └── ◆ __init__.py

File	Role
◆ sessions/__init__.py	Collects local sessions in SESSIONS and session parameters in SESSION_PARAMETERS.
◆ sessions/<session>/__init__.py	Declares either a local SESSION or a caller-supplied SESSION_PARAMETER.

These paths are relative to a subroutine. A workflow owns concrete sessions in the corresponding directories, with its declarations and registry described under Workflow: Session declarations and registry.

Countdown example

Countdown uses one local persistent session for successive decrements.

Source: project.json

{
  "id": "countdown",
  "name": "Countdown",
  "persistent": true
}

This entry in subroutine.sessions declares the countdown resource. It is local to each invocation of the subroutine.

Source: ◆ subroutines/main/sessions/countdown/__init__.py

from typing import Final
from verdog_runtime.declarations import AgentSessionDefinition
from demo.countdown.subroutines.main import SESSION_IDS

SESSION: Final[AgentSessionDefinition] = AgentSessionDefinition(
    id=SESSION_IDS.countdown,
    name='Countdown',
    persistent=True,
)

SESSION records the persistence policy; it contains no provider conversation ID. The decrement node selects this session separately from its decrementer profile. The Agent visit calls context.invoke() without managing conversation IDs itself.

For an input of 2, the first decrement starts a conversation, and the second continues its context through the same logical session. With automatic checkpointing, the runtime preserves committed conversation anchors using copy-on-write; the underlying provider thread ID may therefore change.

A new ordinary subroutine invocation creates a new local countdown session. Reusing the profile alone would not preserve a conversation.