gpt-oss (OpenAI SDK direct)

gpt-oss is the open-weight reasoning model family from OpenAI, native to the Harmony format (channel-aware analysis + final). It has no dedicated agent CLI — instead, use the plain OpenAI Python SDK against rapid-mlx's /v1/chat/completions and let the server's harmony tool + reasoning parsers handle the dual-channel output.

Install

$ pip install openai

Serve gpt-oss

$ rapid-mlx serve gpt-oss-20b-mxfp4-q8 \
    --tool-call-parser harmony \
    --reasoning-parser harmony \
    --enable-auto-tool-choice

Both parsers must be harmony — the model emits <|channel|>analysis for its CoT and <|channel|>final for the user-visible answer. Without --reasoning-parser harmony the analysis channel leaks into content.

OpenAI SDK config

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed",
)

resp = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "Say hello"}],
)
print(resp.choices[0].message.content)

Tool calling

The exact tool-call round-trip the integration matrix runs against every gpt-oss cell (_run_openai_tool_smoke):

resp = client.chat.completions.create(
    model="default",
    messages=[{"role": "user",
               "content": "What's the weather in Tokyo? Use the get_weather tool."}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
    temperature=0.0,
    max_tokens=384,
)
tc = resp.choices[0].message.tool_calls[0]
# tc.function.name == "get_weather", json.loads(tc.function.arguments) == {"city": "Tokyo"}

Harmony features

• Dual channels (analysis + final) — the --reasoning-parser harmony routes analysis into a separate reasoning_content slot on /v1/responses. On chat completions the analysis is suppressed from content.
• Native tool calling — --tool-call-parser harmony parses the model's <|channel|>commentary to=functions.foo prefix; downstream you get standard OpenAI tool_calls.
• ~100% tool-call accuracy on the shipped alias (gpt-oss-20b-mxfp4-q8) — see the integration matrix for the end-to-end pass state.

Gotchas

• User-supplied stop= args are scoped to the final channel. Historically (pre-#1051) the harmony parser applied user stops across both channels, so a stop=['</execute_ipython>'] passed by OpenHands could match the analysis-channel CoT and premature-stop the answer. Fixed in PR #1051.
• Both parsers must be harmony. Setting only --tool-call-parser harmony leaves the analysis channel bleeding into content.

See also