OpenAI Cookbook — Administrator & Developer Guide

This guide covers the architecture, repository structure, tooling internals, configuration reference, and contribution workflow for openai/openai-cookbook. It is written for maintainers, contributors, fork operators, and developers mining the cookbook for reusable patterns.

For everyday usage of the examples, see the User Guide.

1. Architecture Overview

What This Repository Is

The OpenAI Cookbook is a flat collection of runnable examples — primarily Jupyter notebooks and Python scripts — organized by topic under examples/. There is no application to deploy, no server to run, and no build system. The repository exists to teach the OpenAI API through working code.

The only executable Python programs (beyond notebooks) are:

1. examples/api_request_parallel_processor.py — a standalone async script for rate-limited parallel API requests
2. examples/agents_sdk/sandboxed-code-migration/src/run_migration_agent.py — a CLI-driven code migration agent using the Agents SDK

Everything else is notebook-based, designed to be run cell-by-cell in Jupyter.

Repository Layout

openai-cookbook/
├── articles/                    # Markdown articles and GPT-OSS tutorials
│   └── gpt-oss/                 # Open-source model guides (Ollama, vLLM, etc.)
├── examples/                    # 80+ Jupyter notebooks and scripts
│   ├── agents_sdk/              # Agents SDK examples
│   │   ├── sandboxed-code-migration/  # Full migration agent with sandboxes
│   │   ├── multi-agent-portfolio-collaboration/  # Investment analysis agents
│   │   ├── computer_use_with_daytona/  # Computer use example
│   │   └── voice_agents_*/      # Voice agent assets
│   ├── azure/                   # Azure OpenAI examples
│   │   └── archive/             # Deprecated Azure notebooks
│   ├── chatgpt/                 # ChatGPT integrations
│   │   ├── gpt_actions_library/ # 25+ GPT Action recipes
│   │   ├── rag-quickstart/      # RAG on Azure and GCP
│   │   ├── sharepoint_azure_function/  # SharePoint integration
│   │   └── compliance_api/      # Compliance logging
│   ├── codex/                   # Codex examples
│   ├── dalle/                   # DALL-E examples
│   ├── book_translation/        # LaTeX book translation
│   ├── building_w_rt_mini/      # Realtime API mini model
│   ├── agentkit/                # AgentKit walkthrough
│   ├── data/                    # Sample datasets (CSV, JSONL, PDF, audio, DB)
│   └── *.ipynb                  # Top-level notebooks (embeddings, fine-tuning, etc.)
├── authors.yaml                 # Contributor metadata for cookbook.openai.com
├── AGENTS.md                    # Agent instructions
├── CONTRIBUTING.md              # Contribution guidelines
└── LICENSE                      # MIT License

Note

The repository has no setup.py, pyproject.toml, or package configuration. Each example is self-contained — there is no shared library code beyond what individual examples provide in their own subdirectories.

Technology Stack

Component Inventory

2. System Requirements

Development Environment

API Keys and Accounts

3. Configuration Reference

Environment Variables — Complete List

Important

The parallel processor reads OPENAI_API_KEY from the environment if --api_key is not provided on the command line. For Azure deployments, use the --api_key flag or set the environment variable to your Azure API key.

CLI Flags — Parallel Processor (api_request_parallel_processor.py)

CLI Flags — Migration Agent (run_migration_agent.py)

4. Deployment & Scaling

This Repository Does Not Deploy

The cookbook is a collection of examples, not a deployable application. However, some examples contain deployable components:

Azure Functions (RAG Quickstart)

The examples/chatgpt/rag-quickstart/azure/ directory contains an Azure Function for vector similarity search:

• Entry point: function_app.py
• Route: GET /api/vector_similarity_search (anonymous auth)
• Configuration: host.json, requirements.txt
• Deploy: Standard Azure Functions deployment (func azure functionapp publish)

The function accepts JSON requests with search_service_endpoint, index_name, query, k_nearest_neighbors, search_column, and use_hybrid_query fields.

Google Cloud Functions (RAG Quickstart)

The examples/chatgpt/rag-quickstart/gcp/main.py implements a Cloud Function for BigQuery vector search:

• Entry point: openai_docs_search
• Framework: functions-framework
• Deploy: gcloud functions deploy openai_docs_search --runtime python311 --trigger-http

The function accepts JSON with query (required), top_k (default 3), and category (optional filter) fields.

Note

Both RAG quickstart deployments require their respective cloud platforms to be configured separately. The notebooks in the same directories walk through the full setup process.

SharePoint Azure Functions

Two JavaScript Azure Function implementations in examples/chatgpt/sharepoint_azure_function/:

1. solution_one_file_retrieval.js — searches SharePoint via Microsoft Graph, returns raw file content as base64 (suitable for OpenAI file processing)
2. solution_two_preprocessing.js — searches SharePoint, extracts PDF text, then uses gpt-4o-mini to extract relevant passages before returning results

Both require Azure AD OAuth (OBO flow) with TENANT_ID, CLIENT_ID, and MICROSOFT_PROVIDER_AUTHENTICATION_SECRET.

5. Operations

Running the Migration Agent in Production

The sandboxed code migration agent (run_migration_agent.py) is the most operationally complex example in the cookbook.

Docker Backend (Recommended for Local Use)

# Ensure Docker is running
docker info

# Run all migration tasks
python -m src.run_migration_agent --backend docker

# Run specific task
python -m src.run_migration_agent --backend docker --task support_reply_service

The agent creates a Docker container with python:3.14-slim, mounts the fixture repo and migration instructions, runs baseline tests, applies patches, runs final tests, and produces structured output.

Cloudflare Backend (Cloud Sandbox)

export CLOUDFLARE_SANDBOX_WORKER_URL="https://your-worker.workers.dev"
export CLOUDFLARE_SANDBOX_API_KEY="your-key"
python -m src.run_migration_agent --backend cloudflare

Warning

Cloudflare sandbox support requires the cloudflare extra: pip install openai-agents[cloudflare]. If not installed, the agent exits with a clear error message.

E2B Backend (Cloud Sandbox)

export E2B_API_KEY="your-key"
python -m src.run_migration_agent --backend e2b

Monitoring and Auditing

Every migration run produces an audit log at outputs/<task>/migration_audit.jsonl. Events logged:

Tip

Enable --enable-hosted-tracing for detailed run traces in the OpenAI dashboard. This is useful for debugging agent behavior but adds latency.

Artifact Validation

Run the evaluation script to validate migration output:

python evals.py --output-dir outputs/

The validator checks:

• All expected files exist: migration_report.md, migration.patch, migration_result.json, migration_audit.jsonl
• Result JSON contains valid baseline_test_command, check_command, final_test_command
• final_test_result indicates passing tests
• Patch contains responses.create and output_text markers (proving the migration happened)
• Patch modifies the expected files for each task
• Audit log contains a host_artifacts_written event

Yahoo Finance MCP Server

The multi-agent portfolio example includes a FastMCP server for Yahoo Finance data:

python examples/agents_sdk/multi-agent-portfolio-collaboration/mcp/yahoo_finance_server.py

This runs as an MCP stdio server with tools for:

• Historical stock prices
• Stock info and financials
• News
• Stock actions (dividends, splits)
• Financial statements (income, balance sheet, cashflow)
• Holder information
• Options chains
• Analyst recommendations

Files are saved to outputs/ as CSV or JSON. The server has a 30-second timeout per tool call.

6. Performance

Parallel Processor Throughput

The api_request_parallel_processor.py script uses an async event loop with adaptive rate limiting:

• Main loop frequency: 1ms sleep between iterations (max ~1000 requests/second dispatch rate)
• Rate limit cooldown: 15 seconds after receiving a rate limit error
• Capacity tracking: Sliding window for both requests/minute and tokens/minute
• Token estimation: Pre-computed from request JSON using tiktoken before dispatch

Note

The script defaults to 1,500 requests/minute and 125,000 tokens/minute (50% of typical tier limits). Adjust based on your actual rate limits. The defaults are set at 3_000 * 0.5 and 250_000 * 0.5 in the argument parser.

Migration Agent Limits

• Maximum 30 turns per migration task
• Docker containers use python:3.14-slim by default
• MCP server timeout: 30 seconds per session
• Model tool choice: required (agent must use a tool every turn)

7. Security

API Key Handling

All examples read API keys from environment variables or function arguments. No API keys are hardcoded in the repository.

Caution

The parallel processor accepts --api_key as a CLI argument, which means the key appears in shell history. For production use, prefer the OPENAI_API_KEY environment variable.

Azure AD OAuth (SharePoint Examples)

The SharePoint integration uses the OAuth 2.0 On-Behalf-Of (OBO) flow:

1. Client passes a bearer token scoped to the Azure Function
2. Function exchanges it for a Graph API token via the OBO grant
3. Graph API token is used to search and retrieve SharePoint documents

Required secrets: TENANT_ID, CLIENT_ID, MICROSOFT_PROVIDER_AUTHENTICATION_SECRET.

Sandbox Isolation

The migration agent isolates code execution in sandboxes:

Agent instructions explicitly state: "Do not use network access or real API credentials. Keep tests offline."

SQL Injection Risk in GCP RAG Example

The GCP RAG quickstart (main.py) constructs SQL queries using f-strings:

sql_query = f"""
SELECT ... FROM `{project_id}.{dataset_id}.{table_id}` ...
WHERE ed.category = '{category}'
"""

Warning

The category parameter is inserted directly into SQL without parameterization. In a production deployment, use parameterized queries or validate/sanitize the category input to prevent SQL injection.

No Credential Files in Repository

The repository includes .gitignore rules and no credential files are present in source. All requirements.txt files are dependency lists only.

8. Developer Internals

Module Reference

api_request_parallel_processor.py (490 lines)

Production-grade async API request processor. Key components:

Supported endpoints: chat/completions, completions, embeddings. Other endpoints raise NotImplementedError.

Azure support: Detects /deployments in URL and switches from Authorization: Bearer to api-key header.

Retry logic: Failed requests are re-queued with attempts_left - 1. After all attempts exhausted, errors are logged to the save file alongside the original request.

run_migration_agent.py (472 lines)

Sandboxed code migration agent using the OpenAI Agents SDK. Key components:

Default tasks: support_reply_service and case_summary_service (both in repo_fixtures/).

Agent configuration:

• Model: gpt-5.4 (configurable via --model)
• Instructions: "You are a careful code-migration agent" with explicit rules about AGENTS.md, test execution, and offline operation
• Capabilities: Shell() + ApplyPatch()
• Tool choice: required
• Output type: MigrationResult (Pydantic)

Sandbox lifecycle: Client creates session → agent runs in session → client deletes session in finally block (cleanup guaranteed).

Multi-Agent Portfolio Collaboration

A five-agent system for investment analysis:

Agent orchestration pattern: The PM agent has function_tool wrappers that delegate to specialist agents via Runner.run(). A run_all_specialists_parallel tool dispatches all three specialists concurrently using asyncio.gather().

All agents use: gpt-4.1 model, temperature=0, parallel_tool_calls=True.

Code interpreter tool: Uses client.responses.create() with code_interpreter tool type. Uploads input files, downloads generated files (plots, CSVs) from the container.

Prompt management: Prompts live in prompts/ as Markdown files. Loaded via load_prompt() which substitutes <PLACEHOLDER> patterns.

Local tracing: FileSpanExporter writes agent traces to logs/agent_traces.jsonl.

Migration Fixture Repos

Two small Python packages used as test targets for the migration agent:

support_reply_service:

• customer_support_bot/client.py — wraps client.chat.completions.create()
• customer_support_bot/replies.py — drafts support replies using the wrapper
• Tests use FakeOpenAIClient / FakeChatCompletions — fully offline

case_summary_service:

• case_summary_service/client.py — wraps client.chat.completions.create()
• case_summary_service/summaries.py — summarizes case notes using the wrapper
• Tests use the same fake pattern — fully offline

Both repos follow the migration target: Chat Completions → Responses API (client.responses.create(), response.output_text).

Evaluation Script (evals.py)

Validates migration artifacts without re-running the agent:

Code Patterns and Conventions

Notebook Organization

• Each notebook is self-contained — imports, API calls, and outputs in one file
• Notebooks are named descriptively: How_to_<verb>_<noun>.ipynb
• Related notebooks share the examples/ directory; complex examples get subdirectories
• Sample data lives in examples/data/ and is referenced by relative path

Python Script Patterns

• Scripts use argparse for CLI interfaces
• asyncio.run() at the module level for async entry points
• dataclass for internal state tracking
• Pydantic BaseModel for structured agent outputs
• @function_tool decorator from openai-agents for agent tools

Agent Architecture Pattern

The cookbook demonstrates a consistent multi-agent pattern:

1. Define specialist agents with Agent() — each has instructions, tools, and model settings
2. Wrap each specialist in a @function_tool so the orchestrator can delegate
3. Use Runner.run() for sub-agent execution
4. Use asyncio.gather() for parallel specialist execution
5. Collect structured outputs via Pydantic models

MCP Server Pattern

MCP servers use FastMCP from the mcp package:

1. Define sync functions for blocking I/O (e.g., yfinance calls)
2. Wrap in async using loop.run_in_executor() with 30-second timeout
3. Save outputs to CSV/JSON and return metadata (file path, schema, preview)

Testing Strategy

Migration Agent Tests (tests/)

Tests use subprocess.run() to execute unittest discover and compileall against fixture repos.

Migration Evals (evals.py)

Post-run artifact validation (see Operations section above). Run with:

python evals.py --output-dir outputs/

No Global Test Suite

The cookbook has no repository-wide test runner. Individual examples may have tests in their subdirectories.

Note

The fixture repo tests are specifically designed to pass in their pre-migration (Chat Completions) state. The migration agent is expected to update them to pass in the post-migration (Responses API) state.

Repository Files

authors.yaml

YAML file mapping contributor GitHub usernames to display metadata for cookbook.openai.com:

username:
  name: "Display Name"
  website: "https://..."
  avatar: "https://..."

Schema defined by .github/authors_schema.json. If a contributor is not listed, their info is pulled from their GitHub profile.

AGENTS.md

Top-level agent instructions file (content not extracted in briefing — exists at repo root).

CONTRIBUTING.md

Contribution guidelines (content not extracted in briefing — exists at repo root).

Sample Datasets

Potential Improvements

1. Global requirements file — the repository lacks a top-level requirements.txt or pyproject.toml. Adding one with common dependencies would simplify onboarding.

2. Parameterized SQL in GCP RAG — examples/chatgpt/rag-quickstart/gcp/main.py uses f-string SQL construction. Should use parameterized queries.

3. Token estimation coverage — the parallel processor only estimates tokens for completions and embeddings endpoints. Other endpoints raise NotImplementedError.

4. Azure archive cleanup — examples/azure/archive/ contains 7 deprecated notebooks that duplicate functionality in the parent directory.

5. Fixture repo expansion — the migration agent has only 2 fixture repos. Additional fixtures would improve coverage of edge cases.

9. Integration Points

OpenAI API

All examples integrate with the OpenAI API via the openai Python SDK:

Azure OpenAI

The examples/azure/ directory provides direct equivalents for Azure OpenAI Service. Authentication differs (uses api-key header), and deployment URLs follow the /openai/deployments/<name>/ pattern.

MCP (Model Context Protocol)

Two MCP integrations:

1. Yahoo Finance MCP Server (yahoo_finance_server.py): FastMCP stdio server with 9 tools for stock data. Used by fundamental and quantitative analysis agents.

2. OpenAI Docs MCP Server: Optional MCPServerStreamableHttp connection for the migration agent. Fetches Responses API migration documentation at runtime.

Cloud Platform Functions

Third-Party Data Services