Update documentation for responses API mode

[jxnl]

docs: add OpenAI Responses API mode documentation

Describe your changes

This PR updates the OpenAI integration documentation to introduce and explain the new Responses API mode.

The changes include:

• A new "Responses API Mode" section in docs/integrations/openai.md detailing Mode.RESPONSES_TOOLS and Mode.RESPONSES_TOOLS_WITH_INBUILT_TOOLS, including an example.
• Expansion of the "Instructor Modes" list to describe the Responses API modes and clarify their usage compared to classic Chat Completions modes.
• A link to the dedicated OpenAI Responses API guide in the "Related Resources" section.

The goal is to guide users on how to leverage OpenAI's recommended Responses API with Instructor, highlighting benefits like better caching and stateful context, and simplifying the transition between API modes.

Issue ticket number and link

Checklist before requesting a review

• I have performed a self-review of my code
• If it is a core feature, I have added thorough tests.
• If it is a core feature, I have added documentation.

---

Slack Thread

 

---

Important

Updates OpenAI integration documentation to include new Responses API modes and expands Instructor Modes list.

• Documentation:
  • Adds "Responses API Mode" section in openai.md detailing Mode.RESPONSES_TOOLS and Mode.RESPONSES_TOOLS_WITH_INBUILT_TOOLS with example.
  • Expands "Instructor Modes" list to include Responses API modes and clarifies usage compared to Chat Completions modes.
  • Adds link to OpenAI Responses API guide in "Related Resources" section.

^{This description was created by for 72342b8. You can customize this summary. It will automatically update as commits are pushed.}

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	instructor	72342b8	Commit Preview URL Branch Preview URL	Nov 23 2025, 05:14 AM

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 72342b8 in 2 minutes and 41 seconds. Click for details.

• Reviewed 85 lines of code in 1 files
• Skipped 0 files when reviewing.
• Skipped posting 6 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. docs/integrations/openai.md:91

• Draft comment:
  The new 'Responses API Mode' section is clear and provides a helpful async code example. Consider adding a brief note about any prerequisites or version requirements needed to use these modes, and potentially mention that proper error handling might be beneficial in production code.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 85% The comment is purely informative and suggests adding notes about prerequisites and error handling, which is not specific to the code changes. It doesn't align with the rules for making specific code suggestions or asking for tests.

2. docs/integrations/openai.md:431

• Draft comment:
  In the updated Instructor Modes list, the new responses API modes are well integrated. For consistency with other parts of the documentation, consider changing 'Open AI structured outputs API' to 'OpenAI structured outputs API' in the description for instructor.Mode.TOOLS_STRICT.
• Reason this comment was not posted:
  Comment was on unchanged code.

3. docs/integrations/openai.md:462

• Draft comment:
  The addition of the 'OpenAI Responses API Guide' link in the Related Resources section is a solid enhancement that helps users easily find more detailed documentation on the new mode.
• Reason this comment was not posted:
  Confidence changes required: 80% <= threshold 85% None

4. docs/integrations/openai.md:93

• Draft comment:
  Typographical note: There is an inconsistency with the term 'built-in tools'. The documentation refers to them as "built-in tools" while the constant name uses INBUILT (as in RESPONSES_TOOLS_WITH_INBUILT_TOOLS). Consider using consistent spelling (e.g., BUILT_IN or built-in) for clarity.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 85% This is a stylistic/consistency comment about terminology. The constant name uses INBUILT_TOOLS but the documentation uses "built-in tools". While there is technically an inconsistency, this falls into a few problematic categories: 1) It's not clearly a code change that's required - this is more of a stylistic preference, 2) The inconsistency is minor and both terms are commonly understood, 3) Changing the constant name would be a breaking API change, so the only option would be to change the documentation, 4) The comment doesn't clearly indicate which should change - the constant or the docs. The rules say "Do NOT comment unless there is clearly a code change required" and "Do NOT make comments that are obvious or unimportant." This seems like an unimportant stylistic issue that doesn't require action. However, consistency in technical documentation is important for clarity and professionalism. If users see "built-in tools" in the docs but INBUILT_TOOLS in the code, it could cause momentary confusion. This could be considered a legitimate documentation quality issue. While consistency is valuable, this is a very minor issue that doesn't affect functionality or understanding. Both "built-in" and "inbuilt" are clear and mean the same thing. The constant name is already established (likely can't be changed without breaking changes), so this would only be a documentation wording change. This falls under "obvious or unimportant" comments that should be avoided. The user will understand what's meant either way. This comment should be deleted. It's a minor stylistic inconsistency that doesn't require action. The terminology difference between "built-in" and "inbuilt" doesn't affect understanding or functionality, and falls under the category of unimportant comments that should be avoided.

5. docs/integrations/openai.md:425

• Draft comment:
  Typographical: The identifier instructor.Mode.RESPONSES_TOOLS_WITH_INBUILT_TOOLS uses "INBUILT" whereas the description refers to "built-in" tools. Consider renaming it for consistency (e.g., use ..._WITH_BUILT_IN_TOOLS).
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 85% This is a naming consistency comment. The comment is suggesting a refactor to make the constant name match the terminology used in the documentation. However, looking at the diff, this appears to be NEW code being added (lines 93, 425). The constant name RESPONSES_TOOLS_WITH_INBUILT_TOOLS is being introduced in this PR. The comment is about code quality/consistency, which the rules say is good "if actionable and clear." However, this is a constant/enum name that is likely defined in the actual code (not in this markdown file), and changing it would be a breaking change for any users. The comment is also somewhat pedantic - "inbuilt" and "built-in" are synonyms. Most importantly, this is documentation only - the actual constant is defined elsewhere in the codebase, so this comment on the docs file doesn't make sense. The reviewer would need to see the actual code file where the Mode enum is defined to make this suggestion meaningful. The constant name is likely defined in library code elsewhere, not in this documentation file. Changing an API constant name would be a breaking change. Also, "inbuilt" and "built-in" are synonyms, so this is a very minor stylistic preference rather than a real issue. The comment requires cross-file context to be actionable. This comment is about a constant that's defined in another file (the actual Python code), not in this markdown documentation. The documentation is just referencing the constant name. To action this comment, the developer would need to change the constant in the source code, which would be a breaking API change. This requires cross-file context and is not actionable from just this documentation change. Delete this comment. It's about a constant defined in another file (library code), not in this documentation. The rules state to ignore cross-file issues and only think about the file being reviewed. Additionally, changing a public API constant name would be a breaking change, making this suggestion impractical.

6. docs/integrations/openai.md:431

• Draft comment:
  Typographical: The phrase "new Open AI structured outputs API" should probably be "new OpenAI structured outputs API" to maintain consistent branding.
• Reason this comment was not posted:
  Comment was on unchanged code.

Workflow ID: wflow_alazEVjEmF3ymH7w

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}