docs: add OpenAI-compatible agent-server gateway guide

[enyst]

• I have read and reviewed the documentation changes to the best of my ability.
• If the change is significant, I have run the documentation site locally and confirmed it renders as expected.

Summary of changes

• Adds an SDK agent-server guide for the OpenAI-compatible /v1/chat/completions gateway.
• Documents model IDs (openhands_<profile_name>), compatible auth headers, and conversation ID reuse via X-OpenHands-ServerConversation-ID.
• Adds the new guide to the SDK Remote Agent Server navigation and includes the new examples/02_remote_agent_server/14_openai_compatible_gateway.py code block so the agent-sdk documented-examples check passes.

Related SDK PR: OpenHands/software-agent-sdk#3545

This PR was created by an AI agent (OpenHands) on behalf of the user.

@enyst can click here to continue refining the PR

[mintlify]

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

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	Jun 6, 2026, 2:06 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[enyst]

@OpenHands Clone yourself agent-sdk from the same org. Understand the workflow there that verifies companion docs PRs for examples/ files. Check the PR to which this PR is companion and make sure we update this PR if in the meantime, the other PR changed in. a way that affects this.

If you think this PR is in good shape, mark it open for review and /iterate .

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[enyst]

/iterate

Companion SDK PR #3545 was checked against this docs branch. The new docs code block matches examples/02_remote_agent_server/14_openai_compatible_gateway.py, and I added a note for the current non-streaming behavior (stream: true returns 400). Local validation and current PR checks are green.

This comment was created by an AI agent (OpenHands) on behalf of the user.

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

Code Review: PR #554

🟢 Good taste - Well-structured documentation

Summary

This PR adds documentation for the OpenAI-compatible agent-server gateway feature. The documentation is:

• Clear and well-organized: The "How it works" section breaks down the protocol into digestible steps
• Accurate: Correctly describes the model naming pattern (openhands_<profile_name>) and authentication headers
• Complete: Includes the important caveat about streaming not being supported
• Educational: The code example covers the full lifecycle (profile creation → chat → conversation continuation → cleanup)

No Issues Found

• [docs.json] Navigation entry is correctly placed alphabetically
• [openai-gateway.mdx] Frontmatter is properly structured
• [openai-gateway.mdx] Example links to actual source code for long-term maintainability
• [openai-gateway.mdx] Resource cleanup in example follows best practices

Minor Note

The streaming limitation note is important to keep. Make sure it's updated if/when streaming support is added.

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW
  Pure documentation addition with no code changes. No breaking changes, no security concerns, no dependency changes.

VERDICT:
✅ Worth merging: Documentation is accurate, well-structured, and provides good coverage of the feature.

KEY INSIGHT:
The documentation correctly emphasizes the protocol flow and correctly calls out the streaming limitation as a known constraint.

---

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation