[DO NOT MERGE] Preview: OpenAI Agents API tutorial (re-land at launch)

[SystemSculpt]

DO NOT MERGE — preview build only. This PR exists to produce a shareable docs preview of the OpenAI Agents API tutorial for the joint-marketing workshop with OpenAI (target 8/6). The launch-timing revert (#706) still stands: this page must not ship to production docs until the Agents API launches and the cookbook is public.

What

• Reverts the revert (Revert "docs: add the OpenAI Agents API tutorial" (ENG-4186) #706), restoring Tutorials/OpenAI-Agents-API.mdx and its navigation entry exactly as verified in docs: add the OpenAI Agents API tutorial #705.
• Updates the cookbook links for the repository rename to blaxel-ai/blaxel-openai-agents-api-cookbook (clone URL, cd directory, main.py/handoff.py deep links, and the footer card).

Why now

OpenAI extended the Agents API alpha and asked for joint materials ("great developer integration docs" is first on their list) to workshop by 8/6. The tutorial content was already final and verified in #705; this preview lets us include it in the review packet without touching production.

Before this can ever merge (at launch)

• Agents API is publicly launched
• Cookbook repository is public
• Cookbook repins the public Agents API client

---

Note

Adds a "What's next" section (three progressive exercises) to the OpenAI Agents API tutorial and renumbers the existing "Advanced details" heading from §6 to §7.

^{Written by Mendral for commit b55fe9b.}

[mendral-app]

🧪 Testing Guide

What this PR addresses

This PR adds a new tutorial page (Tutorials/OpenAI-Agents-API.mdx) and its navigation entry in docs.json. It re-lands content previously reverted in #706, intended solely for a shareable docs preview build ahead of the joint-marketing workshop with OpenAI (target 8/6). The page documents how to run OpenAI Agents API sessions inside Blaxel Sandboxes with optional Agent Drive persistence.

Steps to verify the preview build

Since this is a documentation-only, draft/preview PR (explicitly marked DO NOT MERGE), testing focuses on the rendered output:

1. Open the deploy preview URL generated by the docs CI (e.g., Mintlify or Vercel preview).
2. Navigate to Tutorials → OpenAI / Codex in the sidebar.
3. Confirm the new "OpenAI Agents API" entry appears as the first item in that group (above "Codex" and "OpenAI Agents SDK Deployment").
4. Click into the page and verify:
   • The Mermaid diagram renders correctly (flowchart LR with four nodes).
   • All tables (Who owns what, storage behavior, "Make it yours") render with correct formatting.
   • The AccordionGroup with five accordions expands/collapses properly.
   • The three Card components at the bottom render with icons and correct hrefs.
   • Internal links (/Sandboxes/Overview, /Agent-drive/Overview, /Sandboxes/Proxy, etc.) resolve without 404s.
   • External links to https://github.com/blaxel-ai/blaxel-openai-agents-api-cookbook (and sub-paths like blob/main/main.py) are valid.
5. Confirm no other pages or navigation items were affected (the rest of the sidebar is unchanged).

What to verify (expected behavior)

• ✅ Preview build deploys successfully with the new page.
• ✅ The page is accessible at the expected path (/Tutorials/OpenAI-Agents-API).
• ✅ All rich content (mermaid, accordions, cards, notes, info callouts, code blocks) renders without errors.
• ✅ The cookbook repository link (blaxel-ai/blaxel-openai-agents-api-cookbook) is correct per the rename mentioned in the PR description.
• ✅ No regression to existing pages — only an additive nav entry in docs.json.

Note

Posted by PR Testing Guide · Tag @mendral-app with feedback.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
blaxel	🟢 Ready	View Preview	Jul 28, 2026, 5:30 PM

[mendral-app]

LGTM

The new commit adds a well-structured "What's next" ladder with internal links (/Sandboxes/Preview-url, /Jobs/Overview) that both resolve to existing pages. No secrets, no logic, no issues. Previous review had no comments to address.

_{Tag @mendral-app with feedback or questions. View session}