跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

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_idstr单独使用：用此 ID 新建；与 fork_session 同用：分叉后新会话的 ID
resumestr要恢复的 session ID
continue_conversationboolTrue 表示恢复最近一次会话
fork_sessionbool配合 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