> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Qwen family best practice

> How to run Qwen and qwen-plus with the native tool-call lane in QitOS.

Qwen in QitOS is no longer just JSON-first by default.

For OpenAI-compatible Qwen endpoints, QitOS now prefers this order:

```text theme={null}
native tool calls -> Decision.act(...) -> tool execution
fallback: json_decision_v1 -> xml_decision_v1 -> react_text_v1
```

This matches the spirit of Qwen-Agent: function calling is the preferred lane when the backend exposes it cleanly.

## What changed in v0.4

The `qwen` family preset (a configuration bundle that maps the Qwen model family to its default protocol, adapter, and tool delivery) now keeps three ideas together:

* tool schemas are delivered through `api_parameter`
* native tool calls are preferred when the endpoint returns `tool_calls`
* text protocols remain available as a stable fallback chain

The default protocol (output format the model is expected to follow) is still `json_decision_v1`, but for Qwen it is now the **text fallback**, not the ideal path itself.

## When the native lane is used

QitOS will prefer the native lane when all of these are true:

* the model resolves to the `qwen` family preset
* the harness (the configured adapter + protocol + toolset combination) metadata says `native_tool_call_preferred = true`
* the OpenAI-compatible response actually contains `tool_calls`

If any of those conditions fail, QitOS falls back to the normal parser (raw-output-to-Decision converter) chain.

## Why QitOS does not copy the Qwen-Agent sentinel prompt

The official Qwen-Agent project includes a Qwen-specific function-calling prompt format for chat interfaces that do not provide a native tool channel.

QitOS does **not** copy that prompt format directly for the OpenAI-compatible Qwen path because:

* OpenAI-compatible serving already gives us a structured `tool_calls` channel
* preserving that structure is cleaner than serializing it back into text
* it keeps the runtime generic enough for other families that also expose native tool calls

Put differently:

* Qwen-Agent solves the more general Qwen chat interface problem
* QitOS solves the OpenAI-compatible served Qwen inside one reusable harness layer problem

## Recommended `qwen-plus` example

Use the flagship example with an OpenAI-compatible Qwen endpoint:

```bash theme={null}
export OPENAI_API_KEY="your_api_key"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"

python examples/real/claude_code_agent.py \
  --model-family qwen \
  --model-name qwen-plus \
  --print-harness
```

You should expect the harness summary to show:

* `family_preset: qwen`
* `tool_delivery: api_parameter`
* `native_tool_call_preferred: True`
* `decision_lane_preference: native_tool_calls`

## How to confirm it in qita

Inspect the run in `qita` and check:

* `family preset` (configuration bundle for a model family)
* `prompt protocol` (output format definition)
* `tool delivery`
* `decision_source` (how the Decision was produced)
* `native_tool_call_used` (whether the native tool-call path was taken)
* `native_tool_call_fallback_reason`

If the endpoint did not return native tool calls, QitOS will still run, but you should see the fallback reason and the parser lane in the trace (the structured run log).