Harmony (cookbook.openai.com)

The gpt-oss models have been trained using the new Harmony response format, a structured conversation protocol designed to clearly separate reasoning, function calls, and user-facing outputs. This format mimics the OpenAI Responses API, categorizing messages by roles—system, developer, user, assistant, and tool—and distributing outputs into three distinct channels: final (user-facing), analysis (chain-of-thought reasoning), and commentary (function call triggers). This layered approach enables precise control over model responses, improves transparency of the reasoning process, and facilitates smooth integration with external functions. For developers building custom inference solutions, adhering to the Harmony format is crucial, as gpt-oss relies on its strict message and token structure for correct operation. The format uses special tokens to define message boundaries, roles, and channels, and tools like the openai_harmony library assist with rendering and parsing these messages efficiently. Advanced features include adjustable reasoning levels (low, medium, high), streaming token decoding, and explicit function call handling via commentary channels, which together enhance model interpretability and extensibility for complex, multi-step tasks. Harmony’s significance lies in its standardized, modular communication scheme that empowers developers to orchestrate detailed conversational workflows with robust tool integration while maintaining clarity between the assistant’s final answers and its internal reasoning. This makes it especially valuable for building sophisticated AI applications requiring explainability, dynamic tool usage, and fine-grained control over model behavior.