[Feature Request] Update to OpenAI response api

[Wendong-Fan]

Required prerequisites

• [x] I have searched the Issue Tracker and Discussions that this hasn't already been reported. (+1 or comment there if it has.)
• [ ] Consider asking first in a Discussion.

Motivation

Supporting the Response API is essential as it unlocks higher intelligence, lower costs, and better performance from OpenAI's reasoning models. refer: https://cookbook.openai.com/examples/responses_api/reasoning_items

Solution

No response

Alternatives

No response

Additional context

No response

[MuggleJinx]

Hi I have evaluated the current implementation. The current implementation directly relies on chat.completions returning a ChatCompletion type, with call sites concentrated in camel/models/openai_model.py:392–510. In contrast, the Response API returns a Response object (with segmented outputs, etc.), which has a completely different structure. This means all downstream logic would require major rewrites.

In higher-level code such as ChatAgent, assertions like isinstance(response, ChatCompletion) are used (see camel/agents/chat_agent.py:2102–2105), and responses are accessed via the old schema choices[*].message. Switching to the Response API would immediately trigger type errors.

The request input formats are also incompatible: OpenAIMessage is defined as ChatCompletionMessageParam (camel/messages/__init__.py:36–44), and the entire pipeline depends on the legacy messages list format. The Response API instead requires the new input/content fragment format, which means existing message constructors, memory management, and token accounting (see camel/utils/token_counting.py:77–119) must all be rewritten.

The codebase also makes heavy use of beta.chat.completions.parse/stream for structured parsing and streaming output (camel/models/openai_model.py:451–509). The Response API’s current responses.parse/stream interfaces are not compatible with these return types and stream managers, so parsing/stream handling wrappers would need to be redesigned.

In summary, chat.completions calls cannot simply be swapped out for responses. To support the Response API, a dedicated backend must be added, with unified rewrites of the message model, return types, streaming, and parsing flow, followed by layer-by-layer adaptation of higher-level logic.

[MuggleJinx]

@Wendong-Fan What do you think we should do next? For openAI compatible model as well, I think they use chat completion API.

[Wendong-Fan]

thanks @MuggleJinx for detailing the dependencies so clearly, I agree it's a significant undertaking. However, I believe this refactoring is necessary for long-term efficiency and performance. To make this manageable, we can break the work down into smaller, parallelizable sub-tasks. We can make the current issue as a parent ticket to track the effort and list out all sub-tasks. We can then assign them to different team members to work on them concurrently. What do you think?

[MuggleJinx]

Cool, sounds good plan!

[hesamsheikh]

Hey @MuggleJinx It would be great if you could break down the task into manageable parts. I can help with some of them as well.

[MuggleJinx]

Hi there! I think we need to make some big adjustment for supporting the new response API, while maintaining the ability for old ChatCompletion API (since we support a lot of OpenAI compatible models). I have design the following roadmap. Feel free to give comments and suggestions!

• Roadmap

• Phase 0 – Planning & Alignment: catalogue every site that consumes ChatCompletion/ChatCompletionMessageParam (agents, memories, token counting, tool handling) and agree on naming/location for the new abstraction modules; RFC or design doc reviewers: core runtime + tooling maintainers.
• Phase 1 (PR 1) – Introduce Camel abstractions with Chat Completion adapter: add camel/core/messages.py + camel/ responses/model_response.py (or similar) defining CamelMessage, CamelToolCall, CamelModelResponse; implement converters that wrap/unwrap the current Chat Completions schema so behaviour is unchanged; update ModelResponse typing, message factories, and unit tests to exercise the new converters; ensure every existing entry point still uses chat.completions via the adapter; goal is a pure refactor with zero functional diff.
• Phase 2 (PR 2) – Retrofit OpenAI backends and agents to the abstraction: migrate OpenAIModel (and other OpenAI- compatible backends) to emit/consume the new types, remove direct isinstance(..., ChatCompletion) checks, adapt streaming/tool-call pipelines to operate over CamelModelResponse; refresh token counting to operate on the abstract representation while still falling back to API-reported usage; update/extend tests for streaming, tools, structured outputs to validate the adapter layer; regression test core agent flows.
• Phase 3 (PR 3) – Responses API backend: add OpenAIResponsesModel implementing the same abstract interface using client.responses.{create,parse,stream}, including request conversion from CamelMessage to Responses input segments and response conversion back to CamelModelResponse; support parallel tool calls, reasoning trace capture, structured outputs, and streaming events; add configuration + model factory wiring (e.g., route O-series models or opt-in flag), plus comprehensive unit/integration tests with mocked Responses data.