Skip to main content
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

FieldTypeBehavior
session_idstrUsed alone: creates with this ID; with fork_session: ID of the new forked session
resumestrSession ID to resume
continue_conversationboolTrue resumes the most recent session
fork_sessionboolUsed 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