qwen-code/packages/sdk-python/README.md

qwen-code-sdk

Experimental Python SDK for programmatic access to Qwen Code through the stream-json protocol.

Installation

pip install qwen-code-sdk

Requirements

• Python >=3.10
• External qwen CLI installed and available in PATH

You can also point the SDK at an explicit CLI binary or script with path_to_qwen_executable.

Quick Start

import asyncio

from qwen_code_sdk import is_sdk_result_message, query


async def main() -> None:
    result = query(
        "List the top-level packages in this repository.",
        {
            "cwd": "/path/to/project",
            "path_to_qwen_executable": "qwen",
        },
    )

    async for message in result:
        if is_sdk_result_message(message):
            print(message["result"])


asyncio.run(main())

Sync API

from qwen_code_sdk import query_sync


with query_sync(
    "Say hello",
    {
        "path_to_qwen_executable": "qwen",
    },
) as result:
    for message in result:
        print(message)

Main APIs

• query(prompt, options=None) -> Query
• query_sync(prompt, options=None) -> SyncQuery
• Query.close(), interrupt(), set_model(), set_permission_mode()
• Query.supported_commands(), mcp_server_status(), get_session_id()

prompt accepts either a single str or an AsyncIterable[SDKUserMessage] for multi-turn sessions.

Permission Callback

from qwen_code_sdk import query


async def can_use_tool(tool_name, tool_input, context):
    if tool_name == "write_file":
        return {"behavior": "deny", "message": "Writes disabled in this app"}
    return {"behavior": "allow", "updatedInput": tool_input}


result = query(
    "Create hello.txt",
    {
        "path_to_qwen_executable": "qwen",
        "can_use_tool": can_use_tool,
    },
)

The callback defaults to deny. If it does not return within 60 seconds, the SDK auto-denies the tool request.

The context argument includes cancel_event, suggestions, and blocked_path when the CLI provides a path-specific permission target. can_use_tool must be an async def callback accepting (tool_name, tool_input, context). stderr must accept a single str.

Errors

• ValidationError: invalid query options or malformed session identifiers
• ControlRequestTimeoutError: CLI control operation exceeded timeout
• ProcessExitError: qwen exited with a non-zero code
• AbortError: query or control request was cancelled

Current Scope

0.1.x is intentionally narrow:

• Uses external qwen CLI via process transport
• Targets stream-json parity with the TypeScript SDK core flow
• Does not yet implement ACP transport
• Does not yet embed MCP servers inside the SDK process

See developer documentation for more detail.