会话控制

QoderSDKClient 默认每次连接启动一个全新的会话。通过 QoderAgentOptions 里几个字段可以指定会话 ID、恢复历史会话或从已有会话分叉。

​

概念

一个 session 对应 CLI 端持久化的一条对话历史（含上下文、工具调用记录、压缩边界等），由 UUID 标识。系统消息 init 里包含本次的 session_id，也是后续 resume / fork_session 的锚点。

​

新建会话

​

默认

不传任何会话相关字段，每次新建：

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():
        ...

​

指定 session ID

让调用方决定 session 的 UUID（适合宿主自己管理 session 索引）：

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():
        ...

​

恢复会话

​

按 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():
        ...

​

恢复最近一次

不知道 session ID 时，用 continue_conversation=True 接上最近修改过的会话：

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():
        ...

resume 和 continue_conversation 不要同时传。

​

分叉会话

从已有会话派生一条新会话，保留原上下文但获得新的 session ID。原会话不受影响：

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():
        ...

要给分叉后的新会话指定 ID：

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

​

字段速查

字段	类型	行为
session_id	str	单独使用：用此 ID 新建；与 fork_session 同用：分叉后新会话的 ID
resume	str	要恢复的 session ID
continue_conversation	bool	True 表示恢复最近一次会话
fork_session	bool	配合 resume 使用，分叉而非接续

​

拿到当前 session ID

init 系统消息的 data 字典里带 session_id；ResultMessage 也带。两者都可以用来记账：

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

​

用户数据目录

用户数据目录用于存放会话历史、资源和日志等 CLI 用户级数据。通过 QoderAgentOptions.env 设置 QODER_CONFIG_DIR，可以指定该目录：

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"},
)