Implementation:Openai Openai agents python Mkdocs Configuration

Knowledge Sources	Openai_Openai_agents_python
Domains	Documentation, Build_Tooling, Configuration
Last Updated	2026-02-11 00:00 GMT

Overview

MkDocs Material configuration file that defines the theme, plugins, navigation structure, internationalization, markdown extensions, and validation rules for the SDK documentation site.

Description

The mkdocs.yml file is the central configuration for the OpenAI Agents SDK documentation site built with MkDocs Material. It defines the site name, repository links, theme settings (Material with black primary palette, code copying/selection features, navigation path/sections/expand, and code annotation support), and custom logo/favicon assets.

The configuration sets up three key plugins: search for full-text search, mkdocstrings for auto-generating API reference documentation from Python docstrings in src/agents (using Google docstring style, source-ordered members, and signature crossrefs), and i18n for internationalization with four locales -- English (default), Japanese, Korean, and Chinese. Each locale has its own complete navigation tree with localized section titles (e.g., "クイックスタート" for Quickstart in Japanese, "빠른 시작" in Korean, "快速开始" in Chinese).

The file also configures Markdown extensions including pymdownx.superfences (with Mermaid diagram support), admonition, pymdownx.details, pymdownx.highlight (with anchor line numbers), pymdownx.inlinehilite, pymdownx.snippets, attr_list, and md_in_html. Validation rules are set to warn on omitted files, absolute links, unrecognized links, and anchors. The site watches src/agents for live reload during development.

Usage

This configuration file is consumed by the mkdocs build tool. It is used when building the documentation site locally (mkdocs serve) or for production deployment (mkdocs build). Modify this file to add new documentation pages, change the site theme, add or update localized navigation, or configure additional plugins and extensions.

Code Reference

Source Location

• Repository: Openai_Openai_agents_python
• File: mkdocs.yml
• Lines: 1-327

Signature

site_name: OpenAI Agents SDK
theme:
  name: material
  features:
    - content.code.copy
    - content.code.select
    - navigation.path
    - navigation.sections
    - navigation.expand
    - content.code.annotate
plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          paths: ["src/agents"]
  - i18n:
      docs_structure: folder
      languages:
        - locale: en
        - locale: ja
        - locale: ko
        - locale: zh

Import

# N/A - This is a configuration file consumed by mkdocs.
# Usage: mkdocs serve / mkdocs build

I/O Contract

Inputs

Name	Type	Required	Description
site_name	string	Yes	The name displayed as the site title
theme	object	Yes	Material theme configuration including features, palette, logo, and favicon
plugins	list	Yes	List of MkDocs plugins (search, mkdocstrings, i18n)
markdown_extensions	list	Yes	List of Markdown extensions for enhanced formatting
validation	object	No	Validation rules for link checking and file inclusion
extra	object	No	Extra configuration including language alternates for i18n switcher

Outputs

Name	Type	Description
Documentation site	HTML	Static HTML site generated by mkdocs build
Localized variants	HTML	Japanese (ja/), Korean (ko/), and Chinese (zh/) versions of the documentation
API Reference	HTML	Auto-generated API reference pages from Python docstrings via mkdocstrings

Usage Examples

Build Documentation Locally

mkdocs serve

Build for Production

mkdocs build

Navigation Structure (English)

nav:
  - Intro: index.md
  - Quickstart: quickstart.md
  - Examples: examples.md
  - Documentation:
      - agents.md
      - running_agents.md
      - Sessions:
          - sessions/index.md
      - results.md
      - streaming.md
      - tools.md
      - mcp.md
      - handoffs.md
      - tracing.md
      - context.md
      - guardrails.md
      - Models:
          - models/index.md
          - models/litellm.md
  - API Reference:
      - Agents:
          - ref/index.md
          - ref/agent.md
          - ref/run.md
      - Tracing:
          - ref/tracing/index.md
      - Realtime:
          - ref/realtime/agent.md
      - Voice:
          - ref/voice/pipeline.md

Related Pages

• Principle:Openai_Openai_agents_python_Documentation_Build_Pipeline