Python SDK 查询

安装进程型 SDK，使用 async query 或同步 query_sync 消费结果与错误。

This page has not been translated into English yet. The original Chinese version is shown below.

qwen-code-sdk 是实验性 Python SDK，导入路径 qwen_code_sdk，要求 Python 3.10+。v1 使用现有 stream-json CLI 协议，只支持进程传输，必须能启动外部 qwen；没有 ACP transport 或 SDK 内嵌 MCP。

安装与环境检查

pip install qwen-code-sdk
qwen --version

预览版本可使用 pip install --pre qwen-code-sdk。qwen 不在目标进程 PATH 时，传 path_to_qwen_executable，可写命令名、绝对二进制路径或 .js bundle。应在实际运行 Python 的环境验证，不以另一个交互 shell 中可用为准。

异步查询

import asyncio
from qwen_code_sdk import is_sdk_result_message, query

async def main():
    async with query(
        "Explain the repository structure.",
        {
            "cwd": "/path/to/project",
            "path_to_qwen_executable": "qwen",
        },
    ) as result:
        async for message in result:
            if is_sdk_result_message(message):
                if message.get("is_error"):
                    print((message.get("error") or {}).get("message", "Unknown error"))
                else:
                    print(message.get("result", ""))

asyncio.run(main())

独立脚本使用 asyncio.run；Jupyter、FastAPI 等已有 event loop 的环境应 await main()，不要再创建嵌套 loop。assistant message 的 content 可能为结构化列表，提取文本时只读取 type 为 text 的 block，不能假定所有内容都是字符串。

同步查询

from qwen_code_sdk import is_sdk_result_message, query_sync

with query_sync(
    "Summarize the repository.",
    {"cwd": "/path/to/project", "path_to_qwen_executable": "qwen"},
) as result:
    for message in result:
        if is_sdk_result_message(message):
            if message.get("is_error"):
                print((message.get("error") or {}).get("message", "Unknown error"))
            else:
                print(message.get("result", ""))

上下文管理器用于清理底层进程。result 消息里的 is_error 与 Python 抛出的异常是两层错误，都需要处理，不能只看到 result 类型就报告成功。

配置范围

配置	用途
cwd、model、env	工作目录、模型覆盖、合并到父环境的差异值
permission_mode、can_use_tool	审批模式与异步 callback
system_prompt、append_system_prompt	替换系统提示或追加指令
max_session_turns	限制轮次数量
core_tools、exclude_tools、allowed_tools	工具注册限制、拒绝与自动批准
include_partial_messages	提供生成中的助手消息
debug、stderr	CLI 诊断输出或逐行接收 hook
timeout	控制操作、权限和流关闭等待，单位为秒

mcp_servers 在 v1 不支持，不能把 TypeScript mcpServers 换成蛇形命名就使用。auth_type 传递 CLI 认证类型，历史 qwen-oauth 标识不是新登录可用性的保证。

错误与诊断

ValidationError 表示非法选项、UUID 或不支持的组合；ControlRequestTimeoutError 表示 initialize/interrupt 等控制等待超时；ProcessExitError 表示 CLI 非零退出；AbortError 表示控制请求或会话取消。

进程启动失败先检查 qwen --version 和路径。debug=True 在没有 stderr hook 时转发 CLI stderr；也可传 stderr=print。控制超时还需检查 CLI 是否支持 --input-format stream-json，以及包装脚本是否吞掉 stdout/stderr，再考虑增加 timeout.control_request。

官方仓库的 npm run smoke:sdk:python -- --qwen qwen 会真实启动 CLI 并调用模型，覆盖异步、控制与同步流程；它不是离线语法检查。会话续接和权限细节见Python 会话控制。