Session Control

By default, QoderSDKClient starts a brand new session with each connection. Through several fields in QoderAgentOptions, you can specify a session ID, resume a historical session, or fork from an existing session.

Concepts

A session corresponds to a persisted conversation history on the CLI side (including context, tool call records, compaction boundaries, etc.), identified by a UUID. The init system message contains the current session_id, which also serves as the anchor point for subsequent resume / fork_session operations.

Creating New Sessions

Default

Without passing any session-related fields, a new session is created each time:

from qoder_agent_sdk import QoderAgentOptions, QoderSDKClient, qodercli_auth

options = QoderAgentOptions(auth=qodercli_auth())

async with QoderSDKClient(options=options) as client:
    await client.query("Hello")
    async for msg in client.receive_response():
        ...

Specifying a Session ID

Let the caller determine the session UUID (suitable when the host manages its own session index):

import uuid

session_id = str(uuid.uuid4())

options = QoderAgentOptions(
    auth=qodercli_auth(),
    session_id=session_id,
)

async with QoderSDKClient(options=options) as client:
    await client.query("Hello")
    async for msg in client.receive_response():
        ...

Resuming Sessions

Resume by ID

options = QoderAgentOptions(
    auth=qodercli_auth(),
    resume="previous-session-id",
)

async with QoderSDKClient(options=options) as client:
    await client.query("Continue the previous conversation")
    async for msg in client.receive_response():
        ...

Resume the Most Recent

When you don’t know the session ID, use continue_conversation=True to pick up the most recently modified session:

options = QoderAgentOptions(
    auth=qodercli_auth(),
    continue_conversation=True,
)

async with QoderSDKClient(options=options) as client:
    await client.query("Continue")
    async for msg in client.receive_response():
        ...

Do not pass resume and continue_conversation simultaneously.

Forking Sessions

Derive a new session from an existing one, preserving the original context but obtaining a new session ID. The original session is unaffected:

options = QoderAgentOptions(
    auth=qodercli_auth(),
    resume="source-session-id",
    fork_session=True,
)

async with QoderSDKClient(options=options) as client:
    await client.query("Based on the prior context, explore a different direction")
    async for msg in client.receive_response():
        ...

To specify an ID for the forked new session:

options = QoderAgentOptions(
    auth=qodercli_auth(),
    resume="source-session-id",
    fork_session=True,
    session_id="my-new-session-id",
)

Field Reference

Field	Type	Behavior
session_id	str	Used alone: creates with this ID; with fork_session: ID of the new forked session
resume	str	Session ID to resume
continue_conversation	bool	True resumes the most recent session
fork_session	bool	Used with resume; forks rather than continues

Getting the Current Session ID

The data dict of the init system message carries session_id; ResultMessage carries it too. Either can be used for bookkeeping:

from qoder_agent_sdk import ResultMessage, SystemMessage

current_session_id = None

async with QoderSDKClient(options=options) as client:
    await client.query("Hello")
    async for msg in client.receive_response():
        if isinstance(msg, SystemMessage) and msg.subtype == "init":
            current_session_id = msg.data["session_id"]
            print(f"session: {current_session_id}")
        elif isinstance(msg, ResultMessage):
            current_session_id = msg.session_id

User data directory

The user data directory stores session history, resources, logs, and other user-level CLI data. Set QODER_CONFIG_DIR through QoderAgentOptions.env to select this directory:

from qoder_agent_sdk import QoderAgentOptions, access_token_from_env

options = QoderAgentOptions(
    auth=access_token_from_env(),
    env={"QODER_CONFIG_DIR": "/var/lib/my-agent/qoder"},
)