feat(OpenAI): add Conversation API

[iBotPeaches]

What:

• Bug Fix
• New Feature

Tasks

• Add endpoints (Conversations)
• Add endpoints (Conversation Files)
• Fix README
• Adjust Conversations to be root-level entity
• Test with real samples
• Migrate Response Items (Retrieve, ListInputItems, Create) into Actions to be re-usable for Conversation Items
• Migrate Response Output into Action
• Migrate Response Tool Choice into Action
• Migrate Response Tools into Action
• Migrate Response Output Text into Action
• Add Tests
• Add Fixtures
• Add Local Shell Call (conv, resp in, resp out)
• Add Local Shell Call Output (conv, resp out)
• Add MCP Approval Response (conv, resp in)
• Add Custom Tool Call (conv, resp out)
• Add Custom Tool Call Output (conv)
• Add Message - Computer Screenshot
• Add Message - Text
• Add Message - Summary Text
• Make Unified Message class to unify Input & Output Messages from Responses

Crossed off things being handled in #671

Description:

Adds Conversation API and Conversation Item API. All endpoints were tested via this sample script.

[iBotPeaches]

I originally designed this under Response API, because this is all its used for at present, but the URL structure of the endpoints does not sit under /responses like say Vector Files or Container Files. So now I believe its a new top level entity, but all its payload/responses are chunks of Response API.

[mydnic]

I originally designed this under Response API, because this is all its used for at present, but the URL structure of the endpoints does not sit under /responses like say Vector Files or Container Files. So now I believe its a new top level entity, but all its payload/responses are chunks of Response API.

Isn't this the replacement of the old Threads API ? I believe the Conversations API is required to be able to migrate from Assistants/Threads/Runs API to the Response API

[iBotPeaches]

Isn't this the replacement of the old Threads API ? I believe the Conversations API is required to be able to migrate from Assistants/Threads/Runs API to the Response API

Yes thats correct.

[iBotPeaches]

There is a lot of overlap, but not perfect with Response API. Once I peeked official JS SDK I noticed.

/**
 * A single item within a conversation. The set of possible types are the same as
 * the `output` type of a
 * [Response object](https://platform.openai.com/docs/api-reference/responses/object#responses/object-output).
 */
export type ConversationItem =
  | ConversationsAPI.Message
  | ResponsesAPI.ResponseFunctionToolCallItem
  | ResponsesAPI.ResponseFunctionToolCallOutputItem
  | ResponsesAPI.ResponseFileSearchToolCall
  | ResponsesAPI.ResponseFunctionWebSearch
  | ConversationItem.ImageGenerationCall
  | ResponsesAPI.ResponseComputerToolCall
  | ResponsesAPI.ResponseComputerToolCallOutputItem
  | ResponsesAPI.ResponseReasoningItem
  | ResponsesAPI.ResponseCodeInterpreterToolCall
  | ConversationItem.LocalShellCall
  | ConversationItem.LocalShellCallOutput
  | ConversationItem.McpListTools
  | ConversationItem.McpApprovalRequest
  | ConversationItem.McpApprovalResponse
  | ConversationItem.McpCall
  | ResponsesAPI.ResponseCustomToolCall
  | ResponsesAPI.ResponseCustomToolCallOutput;

So my changes to the Response InputMessage is invalid as that does not stay true for the Response InputMessages, my indicator is all the classes the official SDK duplicated above instead of re-using the Response API iteration. There must be a reason for each one.

I'll revert changes for Message since I can't unify Response/Conversation into one singular message class. I wish I could, but noticing how official SDK duplicates so many types they must fear the same problem - tiny breaking changes.

[iBotPeaches]

Okay I believe is done now. I'll do some code review on it to double check, but I believe after battle testing it with my own little scripts - its ready.

In this journey I found a few new properties, events in Responses that I need to port over. I'll do those in another PR. This brings in a lot of support for Local Shell & Custom Tool which were not yet typed in Responses or Conversation.

[Copilot]

Pull Request Overview

This PR implements the OpenAI Conversation API, providing functionality to create and manage conversations that can store and retrieve conversation state across Response API calls. The implementation includes comprehensive test coverage and adds support for new message types and tool call outputs.

• Adds Conversation and ConversationItems API endpoints with full CRUD operations
• Introduces new input/output types for local shell calls, custom tool calls, and MCP approval responses
• Includes comprehensive test coverage, fixtures, and documentation updates

Reviewed Changes

Copilot reviewed 49 out of 49 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/Client.php	Adds conversations() method to main client
src/Resources/Conversations.php	Implements conversation CRUD operations
src/Resources/ConversationsItems.php	Implements conversation items management
src/Responses/Conversations/	Response classes for conversation API endpoints
src/Responses/Responses/Input/	New input types for shell calls, custom tools, and MCP responses
src/Responses/Responses/Output/	New output types for shell calls and custom tools
src/Actions/	Parser classes for handling new object types
tests/	Comprehensive test coverage for all new functionality

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[mydnic]

@iBotPeaches I was trying to upgrade my project to migrate from Assistants to Prompts + Conversations by using your latest changes

I got this error however

OpenAI::client(config('services.openai.key'))->conversations()->create()

OpenAI\Exceptions\ErrorException Unknown beta requested: 'assistants'.

[iBotPeaches]

OpenAI\Exceptions\ErrorException Unknown beta requested: 'assistants'.

Hmm that would be problematic - since that header is applied by default here - https://github.com/openai-php/client/blob/main/src/OpenAI.php#L19

Not sure why I'm not replicating, but I'll dig into this

[mydnic]

OpenAI\Exceptions\ErrorException Unknown beta requested: 'assistants'.

Hmm that would be problematic - since that header is applied by default here - https://github.com/openai-php/client/blob/main/src/OpenAI.php#L19

Not sure why I'm not replicating, but I'll dig into this

yeah when I comment this line, it works.

[iBotPeaches]

yeah when I comment this line, it works.

thanks. Still researching, but started this - #688