• The technical problems that the Harmony format solves
• The role definitions of system / developer / user / assistant / tool
• The separation of output into the three channels analysis / commentary / final
• How reasoning (reasoning / CoT), tool calls, and structured output are represented
• A complete list of the publicly documented special tokens and the criteria for their use
• The treatment of additional token candidates that exist within the openai/harmony implementation but are not published in the tokenizer configuration
• The actual processing logic in Hugging Face's chat_template.jinja
• Concrete conversation examples, tool-use examples, and implementation examples

• The hierarchical structure of the conversation (system / developer / user / assistant / tool)
• The model's internal reasoning (analysis)
• Intermediate notices to the user (commentary) and the final answer (final)
• Calls to user-defined functions (function tools)
• Execution of built-in tools (browser / python)
• Structured output (output based on JSON Schema, etc.)

• The assistant's output can be split into independent channels: analysis / commentary / final.
• The end of a tool call is controlled by the <|call|> token.
• The end of a final answer is controlled by the <|return|> token.
• When constructing the conversation history for the next turn, the terminating <|return|> can be normalized to <|end|>, which indicates a completed state.
• A reasoning process (reasoning) can be interleaved within the sequence of tool calls.
• A response format (with a schema definition) can be embedded within a developer message.

1. OpenAI Cookbook: OpenAI Harmony Response Format https://developers.openai.com/cookbook/articles/openai-harmony
2. GitHub: openai/harmony https://github.com/openai/harmony
3. openai/harmony Python API docs
   https://github.com/openai/harmony/blob/main/docs/python.md
4. openai/harmony implementation code (src/encoding.rs)
   https://github.com/openai/harmony/blob/main/src/encoding.rs
5. GitHub: openai/gpt-oss https://github.com/openai/gpt-oss
6. OpenAI Cookbook: How to run gpt-oss with Hugging Face Transformers https://github.com/openai/openai-cookbook/blob/main/articles/gpt-oss/run-transformers.md

1. Hugging Face openai/gpt-oss-20b chat_template.jinja
   https://huggingface.co/openai/gpt-oss-20b/blob/main/chat_template.jinja
2. Hugging Face openai/gpt-oss-20b tokenizer_config.json
   https://huggingface.co/openai/gpt-oss-20b/blob/main/tokenizer_config.json
3. vLLM Recipe: GPT OSS https://docs.vllm.ai/projects/recipes/en/latest/OpenAI/GPT-OSS.html
4. Ollama gpt-oss template blob
   https://ollama.com/library/gpt-oss%3A20b/blobs/51468a0fd901

• The official documentation (2.1) is treated as the primary source of information.
• However, because actual system behavior depends on the chat template, tokenizer configuration, and library implementation, these secondary sources (2.2) are also comprehensively evaluated as part of the specification.
• Where discrepancies between the official documentation and the actual implementation / templates are confirmed, those differences are noted explicitly.
• For special tokens whose purpose is not published, they are treated as "undefined" or "unknown," and no meaning is assigned by conjecture.

1. Execution of internal reasoning (CoT) via the analysis channel
2. Intermediate notices to the user via the commentary channel (e.g., a declaration such as "I will begin searching")
3. Function / tool calls (Tool Call) via the commentary or analysis channel
4. Reading of tool execution results
5. Output of the final answer via the final channel

• Priority: system > developer > user > assistant > tool

• A fixed identity (e.g., You are ChatGPT, a large language model trained by OpenAI.)
• The knowledge cutoff (Knowledge cutoff: ...)
• The current date (Current date: ...)
• The reasoning level (Reasoning: low | medium | high)
• Definitions of built-in tools
• Declaration of the valid channels

messages = [
    {"role": "system", "content": "Always answer in Japanese."},
    {"role": "user", "content": "Hello"},
]

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2026-04-04

Reasoning: medium

# Valid channels: analysis, commentary, final. Channel must be included for every message.<|end|>
<|start|>developer<|message|># Instructions

Always answer in Japanese.

<|end|>
<|start|>user<|message|>Hello<|end|>
<|start|>assistant

<|start|>assistant<|channel|>analysis<|message|>Need to verify the date before answering.<|end|>

<|start|>assistant<|channel|>commentary<|message|>I'll answer after confirming the latest information.<|end|>

<|start|>assistant<|channel|>final<|message|>The conclusion is 42.<|return|>

<|start|>{header}<|message|>{content}<|end|>

• An ordinary completed message: <|end|>
• Completion of generating a final answer (decoding stops): <|return|>
• Completion of generating a tool call (decoding stops): <|call|>

message      := "<|start|>" header "<|message|>" content terminator
header       := author [recipient] [channel] [content_type]
author       := role | role ":" name | tool_name
recipient    := " to=" recipient_name
channel      := "<|channel|>" channel_name
content_type := " " plain_type | " <|constrain|>" constrained_type
terminator   := "<|end|>" | "<|return|>" | "<|call|>"

<|start|>assistant to=functions.get_current_weather<|channel|>commentary <|constrain|>json<|message|>{"location":"Tokyo"}<|call|>

• <|start|>: The token indicating the start of the message.
• assistant: The role of the sender.
• to=functions.get_current_weather: The specification of the function being called.
• <|channel|>commentary: The channel being used.
• <|constrain|>json: The data type of the payload.
• <|message|>: The boundary token between the header and the body (content).
• {"location":"Tokyo"}: The body (JSON-formatted arguments).
• <|call|>: The terminating token for a tool call. Reasoning stops here and transitions to the tool execution process.

<|start|>user<|message|>What is 2 + 2?<|end|>
<|start|>assistant

<|channel|>analysis<|message|>...

• A fixed identity: for example, specify something like "You are ChatGPT, a large language model trained by OpenAI."
• Knowledge cutoff: specify the knowledge cutoff date.
• Current date: specify the current date.
• Reasoning: specify the degree of reasoning as one of low, medium, or high.
• built-in tools: define built-in tools as needed.
• valid channels: declare the valid channels (analysis, commentary, final).
• Specification of function tools: when using function tools, add a statement instructing that those tools be called on the commentary channel.

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2026-04-04

Reasoning: high

# Valid channels: analysis, commentary, final. Channel must be included for every message.<|end|>

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2026-04-04

Reasoning: high

# Valid channels: analysis, commentary, final. Channel must be included for every message.
Calls to these tools must go to the commentary channel: 'functions'.<|end|>

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2026-04-04

Reasoning: medium

# Tools

## browser

// Tool for browsing.
// The `cursor` appears in brackets before each browsing display: `[{cursor}]`.
// Cite information from the tool using the following format:
// `〖{cursor}†L{line_start}(-L{line_end})?〗`, for example: `〖6†L9-L11〗` or `〖8†L3〗`.
// Do not quote more than 10 words directly from the tool output.
// sources=web (default: web)
namespace browser {

type search = (_: {
query: string,
topn?: number, // default: 10
source?: string,
}) => any;

type open = (_: {
id?: number | string, // default: -1
cursor?: number, // default: -1
loc?: number, // default: -1
num_lines?: number, // default: -1
view_source?: boolean, // default: false
source?: string,
}) => any;

type find = (_: {
pattern: string,
cursor?: number, // default: -1
}) => any;

} // namespace browser

## python

Use this tool to execute Python code in your chain of thought. The code will not be shown to the user.
When you send a message containing Python code to python, it will be executed in a stateful Jupyter notebook environment...

# Valid channels: analysis, commentary, final. Channel must be included for every message.<|end|>

• # Instructions
• # Tools
• # Response Formats

<|start|>developer<|message|># Instructions

Please answer in Japanese, keeping bullet points to a minimum.<|end|>

<|start|>developer<|message|># Instructions

Please answer in a friendly tone.

# Tools

## functions

namespace functions {

// Returns the current location
type get_location = () => any;

// Returns the current weather for the specified city
type get_current_weather = (_: {
// City name. Example: "Tokyo"
location: string,
// Unit
format?: "celsius" | "fahrenheit", // default: celsius
}) => any;

} // namespace functions<|end|>

<|start|>developer<|message|># Instructions

You are a shopping-list creation assistant.

# Response Formats

## shopping_list

{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"},"description":"shopping items"}},"required":["items"]}<|end|>

<|start|>user<|message|>Tell me today's temperature in Tokyo.<|end|>

<|start|>user:alice<|message|>Hello<|end|>

1. analysis: internal reasoning
2. commentary: intermediate explanations to the user and preambles
3. final: the final answer
4. Tool calls (tool call) with a to=... attribute

<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|return|>

<|start|>assistant<|channel|>analysis<|message|>The user is asking simple arithmetic. Answer directly.<|end|>

<|start|>assistant<|channel|>commentary<|message|>First, I'll confirm the official information.<|end|>

<|start|>assistant<|channel|>analysis<|message|>Need to use function get_current_weather.<|end|>
<|start|>assistant<|channel|>commentary to=functions.get_current_weather <|constrain|>json<|message|>{"location":"San Francisco"}<|call|>

<|start|>assistant to=functions.get_current_weather<|channel|>commentary json<|message|>{"location":"San Francisco"}<|call|>

• The plain-text "json"
• The special-token form "<|constrain|>json"

<|start|>functions.get_current_weather to=assistant<|channel|>commentary<|message|>{"sunny":true,"temperature":20}<|end|>

<|start|>python to=assistant<|channel|>analysis<|message|>55<|end|>

<|start|>browser.search to=assistant<|channel|>analysis<|message|>[12] Bank of Japan - Policy Interest Rate<|end|>

• gpt-oss functions as a reasoning model.
• The reasoning effort is specified as one of low, medium, or high.
• The raw reasoning process (CoT: Chain of Thought) is emitted on the analysis channel.
• The content of the analysis channel is, by specification, hidden from the end user.
• The final answer to the user is emitted via the final channel.

<|start|>user<|message|>What is 2 + 2?<|end|>
<|start|>assistant

<|channel|>analysis<|message|>User asks: "What is 2 + 2?" Simple arithmetic. Provide answer.<|end|>
<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|return|>

• The final answer at the point generation stops: <|return|>
• When storing as conversation history: <|end|>

<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|return|>

<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|end|>

1. Output of analysis
2. Output of the tool call
3. Receipt of the tool execution result
4. Continuation of reasoning, or output of final

<|start|>assistant<|channel|>analysis<|message|>Need to use function get_current_weather.<|end|>
<|start|>assistant<|channel|>commentary to=functions.get_current_weather <|constrain|>json<|message|>{"location":"San Francisco"}<|call|>
<|start|>functions.get_current_weather to=assistant<|channel|>commentary<|message|>{"sunny": true, "temperature": 20}<|end|>
<|start|>assistant

• openai-harmony implements RenderConversationConfig(auto_drop_analysis=True).
• The Hugging Face chat_template.jinja contains logic that discards preceding tool-CoT and analysis when a subsequent final exists.

• It assumes at most one tool call per assistant message.
• The tool name in a tool-role message is inferred from the name of the immediately preceding assistant tool call.
• An assistant tool call message that contains both content and thinking simultaneously is handled as an exception.

• Declare namespaces in the form namespace functions { ... }.
• Define a function with no arguments as type foo = () => any;.
• Define a function with arguments as type foo = (_: { ... }) => any;.
• Write a description (comment) above each field using //.
• Always specify the return type as any.

# Tools

## functions

namespace functions {

// Returns the user's location information
type get_location = () => any;

// Returns the current weather for the specified city
type get_current_weather = (_: {
// City name. Example: "Tokyo"
location: string,
// Temperature unit
format?: "celsius" | "fahrenheit", // default: celsius
}) => any;

// Retrieves the weather for multiple cities at once
type get_multiple_weathers = (_: {
// List of cities
locations: string[],
format?: "celsius" | "fahrenheit", // default: celsius
}) => any;

} // namespace functions

• Array types are converted to string[], number[], boolean[], etc.
• Enum types are converted to union types like "a" | "b" | "c".
• Properties that are not required have ? appended.
• Default values are noted as comments in the form // default: ....
• Complex union types and object types may fall back to the any type.

• browser
• python

• Web search
• Expanding (opening) web pages
• In-page search
• Citing information with line numbers

## browser

// Tool for browsing.
// The `cursor` appears in brackets before each browsing display: `[{cursor}]`.
// Cite information from the tool using the following format:
// `〖{cursor}†L{line_start}(-L{line_end})?〗`
// Do not quote more than 10 words directly from the tool output.
// sources=web (default: web)
namespace browser {

type search = (_: {
query: string,
topn?: number, // default: 10
source?: string,
}) => any;

type open = (_: {
id?: number | string, // default: -1
cursor?: number, // default: -1
loc?: number, // default: -1
num_lines?: number, // default: -1
view_source?: boolean, // default: false
source?: string,
}) => any;

type find = (_: {
pattern: string,
cursor?: number, // default: -1
}) => any;

} // namespace browser

<|start|>assistant<|channel|>analysis<|message|>Need to verify the latest policy rate from an official source.<|end|>
<|start|>assistant to=browser.search<|channel|>analysis <|constrain|>json<|message|>{"query":"site:boj.or.jp policy rate","topn":5,"source":"web"}<|call|>
<|start|>browser.search to=assistant<|channel|>analysis<|message|>[12] Bank of Japan - Monetary Policy<|end|>
<|start|>assistant to=browser.open<|channel|>analysis <|constrain|>json<|message|>{"cursor":12,"id":0,"loc":120,"num_lines":20,"source":"web"}<|call|>
<|start|>browser.open to=assistant<|channel|>analysis<|message|>[13]
L120: ...
L121: ...
L122: ...<|end|>
<|start|>assistant<|channel|>final<|message|>According to the official material, the policy rate is stated as 0.5%. 〖13†L120-L122〗<|return|>

• Computation within the internal reasoning process
• Data formatting
• Execution of small pieces of code
• Preparation of final deliverables (tables, figures, files, etc.)

• Python code can be executed as part of the Chain-of-Thought (CoT) process.
• The executed code is, by premise, hidden from the end user.
• A stateful, Jupyter-notebook-like environment is provided.
• A timeout constraint exists on execution.
• Access to the /mnt/data directory is permitted.
• Whether internet access is available depends on the environment settings of the hosting cluster and is not uniform.

<|start|>assistant<|channel|>analysis<|message|>Need exact computation for the sum of squares from 1 to 5.<|end|>
<|start|>assistant to=python<|channel|>analysis<|message|>sum(i*i for i in range(1, 6))<|call|>
<|start|>python to=assistant<|channel|>analysis<|message|>55<|end|>
<|start|>assistant<|channel|>final<|message|>The sum from 1^2 to 5^2 is 55.<|return|>

# Response Formats

## {format_name}

// Optional description
{json_schema}

<|start|>developer<|message|># Instructions

You are a shopping assistant.

# Response Formats

## shopping_list

{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"},"description":"entries on the shopping list"}},"required":["items"]}<|end|>
<|start|>user<|message|>I want to buy coffee, eggs, and milk.<|end|>
<|start|>assistant

<|start|>assistant<|channel|>final<|message|>{"items":["coffee","eggs","milk"]}<|return|>

• <|reserved_200000|>
• <|reserved_200001|>
• <|reserved_200004|>
• <|reserved_200009|>
• <|reserved_200010|>
• <|reserved_200011|>
• <|reserved_200013|>
• <|reserved_200014|>
• <|reserved_200015|>
• <|reserved_200016|>
• <|reserved_200017|>

• bos_token = "<|startoftext|>"
• eos_token = "<|return|>"
• pad_token = "<|endoftext|>"

<|start|>user<|message|>Hello<|reserved_200015|><|end|>

• <|refusal|>
• <|untrusted|>
• <|end_untrusted|>
• <|meta_end|>

<|start|>assistant<|channel|>final<|refusal|><|message|>...

<|start|>functions.search_docs to=assistant<|channel|>commentary<|message|>{"results":[...]}<|end|>

• Output example:

<|start|>assistant<|channel|>commentary<|message|>Work plan:
1. Search the official site
2. Open the PDF
3. Summarize the key points
I'll proceed in order.<|end|>

• Input message:

<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2026-04-04

Reasoning: high

# Valid channels: analysis, commentary, final. Channel must be included for every message.<|end|>
<|start|>user<|message|>What is 2 + 2?<|end|>
<|start|>assistant

• Model output:

<|channel|>analysis<|message|>The user is asking a simple addition. Just answer directly.<|end|>
<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|return|>

• Normalization of the history data for the next turn:

<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|end|>

• Tool definition (placed in the developer role):

<|start|>developer<|message|># Instructions

Please answer weather questions concisely.

# Tools

## functions

namespace functions {

// Returns the current weather for the specified city
type get_current_weather = (_: {
// City name
location: string,
}) => any;

} // namespace functions<|end|>

• User input:

<|start|>user<|message|>What's the weather in San Francisco?<|end|>
<|start|>assistant

• First model output (tool call):

<|channel|>analysis<|message|>Need to use function get_current_weather.<|end|>
<|start|>assistant<|channel|>commentary to=functions.get_current_weather <|constrain|>json<|message|>{"location":"San Francisco"}<|call|>

• Returning the tool execution result:

<|start|>functions.get_current_weather to=assistant<|channel|>commentary<|message|>{"sunny":true,"temperature":20,"unit":"celsius"}<|end|>
<|start|>assistant

• Second model output (final answer):

<|channel|>analysis<|message|>Tool says sunny and 20C. Provide concise final answer.<|end|>
<|start|>assistant<|channel|>final<|message|>San Francisco is sunny, 20°C.<|return|>

• Specification notes:
  • The output of the analysis channel is hidden from the user.
  • The tool call stops at the <|call|> token.
  • After returning the execution result, <|start|>assistant is appended at the end to resume generation.

• Example execution sequence:

<|start|>assistant<|channel|>analysis<|message|>Need an official and recent source from the Bank of Japan website.<|end|>
<|start|>assistant to=browser.search<|channel|>analysis <|constrain|>json<|message|>{"query":"site:boj.or.jp policy interest rate","topn":5,"source":"web"}<|call|>
<|start|>browser.search to=assistant<|channel|>analysis<|message|>[12] Bank of Japan - Monetary Policy Meetings<|end|>
<|start|>assistant to=browser.open<|channel|>analysis <|constrain|>json<|message|>{"cursor":12,"id":0,"loc":120,"num_lines":10,"source":"web"}<|call|>
<|start|>browser.open to=assistant<|channel|>analysis<|message|>[13]
L120: ...
L121: The uncollateralized overnight call rate ...
L122: ...
<|end|>
<|start|>assistant<|channel|>final<|message|>According to the Bank of Japan's official material, the target for the uncollateralized overnight call rate is stated as 0.5%. 〖13†L121-L122〗<|return|>

• Specification notes:
  • The browser tool is executed on the analysis channel as a rule.
  • For citations in the final answer, use the line-number format (〖cursor†Lx-Ly〗).
  • Direct string quotations from tool output are limited to 10 words or fewer due to template constraints.

• Example execution sequence:

<|start|>assistant<|channel|>analysis<|message|>Need exact calculation; using python is simplest.<|end|>
<|start|>assistant to=python<|channel|>analysis<|message|>sum(i*i for i in range(1, 6))<|call|>
<|start|>python to=assistant<|channel|>analysis<|message|>55<|end|>
<|start|>assistant<|channel|>final<|message|>The sum from 1^2 to 5^2 is 55.<|return|>

• Specification notes:
  • The execution of Python code itself is visible in the format, but because it uses the analysis channel, the design principle is not to display it in the user UI.

• Example execution sequence:

<|start|>assistant<|channel|>analysis<|message|>Need a multi-step plan involving file generation and server startup.<|end|>
<|start|>assistant<|channel|>commentary<|message|>Work plan:
1. Generate the HTML file
2. Generate the Node.js server code
3. Confirm startup
---
I'll execute them in order.<|end|>
<|start|>assistant to=functions.generate_file<|channel|>commentary <|constrain|>json<|message|>{"template":"basic_html","path":"index.html"}<|call|>

• Specification notes:
  • commentary functions as an intermediate report to the user about the most recent processing.
  • final is positioned as the final deliverable after all processing is complete.

• developer configuration example:

<|start|>developer<|message|># Instructions

Please return only the shopping list.

# Response Formats

## shopping_list

{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}}},"required":["items"]}<|end|>

• User input:

<|start|>user<|message|>I need coffee, sparkling water, and eggs.<|end|>
<|start|>assistant

• Output example:

<|start|>assistant<|channel|>final<|message|>{"items":["coffee","sparkling water","eggs"]}<|return|>

from openai_harmony import (
    HarmonyEncodingName,
    load_harmony_encoding,
    Conversation,
    Message,
    Role,
    SystemContent,
    DeveloperContent,
)

encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)

convo = Conversation.from_messages([
    Message.from_role_and_content(Role.SYSTEM, SystemContent.new()),
    Message.from_role_and_content(
        Role.DEVELOPER,
        DeveloperContent.new().with_instructions("Always answer in Japanese")
    ),
    Message.from_role_and_content(Role.USER, "What is 2 + 2?"),
])

prefill_ids = encoding.render_conversation_for_completion(convo, Role.ASSISTANT)
stop_ids = encoding.stop_tokens_for_assistant_actions()

• Key APIs:
  • render_conversation_for_completion(...)
  • render_conversation_for_training(...)
  • render_conversation(...)
  • parse_messages_from_completion_tokens(...)
  • stop_tokens()
  • stop_tokens_for_assistant_actions()
  • StreamableParser(...)
• RenderConversationConfig settings:
  • By setting the auto_drop_analysis=True parameter, unnecessary analysis data can be automatically excluded during history rendering.
  • This feature prevents unnecessary reasoning processes from accumulating in the conversation history.

• Implementation example:

from transformers import AutoTokenizer, AutoModelForCausalLM

model_name = "openai/gpt-oss-20b"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype="auto", device_map="auto")

messages = [
    {"role": "system", "content": "Always answer in Japanese."},
    {"role": "user", "content": "What is MXFP4?"},
]

inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
    return_dict=True,
).to(model.device)

• Notes on implementation:
  • A system role defined at the head is automatically treated as a Harmony developer role.
  • The proper Harmony system message is automatically generated by the template.
  • Specifying add_generation_prompt=True appends <|start|>assistant, the generation-start trigger, at the end.
  • The template provides arguments such as builtin_tools, model_identity, and reasoning_effort, and the default value of reasoning_effort is medium.

• /v1/responses:
  • Supports tool execution in the middle of reasoning (Chain-of-Thought).
  • Can process the entire flow up to the final response.
  • The openai-harmony library is used to render the input and parse the output.
  • Stateful operation and full streaming processing are currently work in progress (WIP).
• /v1/chat/completions:
  • Provides a standard chat completion interface, but does not perform tool execution.
  • Can return the reasoning data and the final text in a structured form.
  • Specifying include_reasoning: false excludes the reasoning process from the response.
• /v1/completions:
  • Supports only plain input/output; the advanced features of Harmony must be handled on the client side.
• Startup arguments to enable Function Calling:

vllm serve ... --tool-call-parser openai --enable-auto-tool-choice

1. Write application-specific instructions in the developer role
   Do not include all instructions in the system role.
2. Do not retain the trailing <|return|> of the final channel in the history
   When retaining it as history for the next turn, normalize the terminating token to <|end|>.
3. Do not display the output of the analysis channel to the end user
   By the design of the Harmony format, analysis is treated as explicitly separated internal reasoning.
4. Stop tool calls at <|call|>
   After that, return the tool execution result to the model as a tool message.
5. Do not manually insert reserved tokens
   Even if a definition exists in the tokenizer, its meaning is not guaranteed as a public specification.
6. Use the standard template or renderer rather than a custom implementation
   To avoid the risk of the parser erroring due to minor syntax differences.
7. Conform to the behavior of the Hugging Face (HF) template
   • A system message is automatically converted to a Harmony developer message.
   • It assumes one tool call per assistant message.
   • After generating the final response, it discards the preceding CoT (Chain of Thought) history.
8. Be aware of the difference between <|constrain|>json and plain-text json
   The syntax examples differ between the official Cookbook and the HF template, but the library implementation accepts both forms.

• When using Transformers
  Use tokenizer.apply_chat_template(...).
• When implementing custom generation processing
  Apply the renderer and parser of the openai-harmony library.
• When building an inference server
  Choose middleware that natively supports the Harmony format, such as vLLM, Ollama, or an official compatibility layer.

• Verifying the behavior of parsers and renderers
• Academic or technical research purposes
• Development of compatible implementations
• Debugging work at the tokenizer or protocol level

• Harmony is a format designed for gpt-oss models to handle "conversation," "reasoning," "tool use," and "structured output" in a unified way.
• The system role is used to define meta-information, and application-specific instructions are defined in the developer role.
• The output of the assistant role is separated into the three channels analysis, commentary, and final.
• The terminating token for a tool call is <|call|>, and the terminating token for a final answer is <|return|>.
• When retaining as history for the next turn, the terminating token must be replaced (normalized) from <|return|> to <|end|>.
• User-defined function tools are normally called from the commentary channel, and the built-in browser and python tools are normally called from the analysis channel.
• The HF chat template reinterprets the system message at the head of the input as the Harmony developer role.
• The tokenizer defines 21 added special tokens, but the majority are treated as reserved tokens.
• The openai/harmony implementation includes additional format tokens that do not exist in the public tokenizer, but avoid manually entering these for gpt-oss.
• For implementation, the standard is to use the openai-harmony library or the official chat template.

• OpenAI Cookbook / OpenAI Harmony Response Format
  https://developers.openai.com/cookbook/articles/openai-harmony
• openai/harmony
  https://github.com/openai/harmony
• openai/harmony Python API docs
  https://github.com/openai/harmony/blob/main/docs/python.md
• openai/harmony src/encoding.rs
  https://github.com/openai/harmony/blob/main/src/encoding.rs
• openai/gpt-oss
  https://github.com/openai/gpt-oss
• OpenAI Cookbook / How to run gpt-oss with Hugging Face Transformers
  https://github.com/openai/openai-cookbook/blob/main/articles/gpt-oss/run-transformers.md
• Hugging Face openai/gpt-oss-20b chat_template.jinja
  https://huggingface.co/openai/gpt-oss-20b/blob/main/chat_template.jinja
• Hugging Face openai/gpt-oss-20b tokenizer_config.json
  https://huggingface.co/openai/gpt-oss-20b/blob/main/tokenizer_config.json
• vLLM Recipes / GPT OSS
  https://docs.vllm.ai/projects/recipes/en/latest/OpenAI/GPT-OSS.html
• Ollama gpt-oss template blob
  https://ollama.com/library/gpt-oss%3A20b/blobs/51468a0fd901