fix: improve OpenAI message content compatibility

[Genmin]

Summary

• add a concrete fallback generate_stream implementation for OpenAIAugmentedLLM, so the provider remains instantiable after streaming became an abstract LLM API
• serialize text-only MCP sampling message content as plain strings in MCPOpenAITypeConverter
• keep non-text MCP content as OpenAI content-part arrays so multimodal inputs are preserved

Notes

Refs #25, especially the from_mcp_message_param() follow-up reported in the issue thread. I intentionally left the tool-result execute_tool_call() path alone because #680 and #651 already cover that primary fix.

Testing

• uv run --extra openai --group dev pytest tests/workflows/llm/test_augmented_llm_openai.py -q
• uv run --extra openai --group dev ruff check src/mcp_agent/workflows/llm/augmented_llm_openai.py tests/workflows/llm/test_augmented_llm_openai.py
• uv run --extra openai --group dev ruff format --check src/mcp_agent/workflows/llm/augmented_llm_openai.py tests/workflows/llm/test_augmented_llm_openai.py
• git diff --check

Summary by CodeRabbit

Release Notes

• New Features

  • Added streaming capability for LLM responses, enabling real-time event-based output of generated messages.

• Improvements

  • Enhanced message content formatting for improved efficiency with text handling and better support for multimedia content types.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds streaming support to OpenAIAugmentedLLM via a generate_stream method that emits event-based output. It also refactors message content conversion to represent text as raw strings and non-text content as content-part lists, introducing the mcp_content_to_openai_message_content helper.

Changes

Cohort / File(s)	Summary
Streaming and Content Conversion src/mcp_agent/workflows/llm/augmented_llm_openai.py	Adds generate_stream method for streaming output with TEXT_DELTA and COMPLETE events. Introduces mcp_content_to_openai_message_content helper to convert MCP content: text as raw strings, non-text as content-part lists.
Test Updates tests/workflows/llm/test_augmented_llm_openai.py	Updates type-conversion assertions to expect text MCP content as plain strings rather than lists. Adds test coverage for ImageContent conversion to OpenAI-compatible structured content parts.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Fix openai workflow for handling images #341: Modifies OpenAI conversion logic for MCP message content representation, directly overlapping with content conversion changes in this PR.

Suggested reviewers

• saqadri
• rholinshead

Poem

🐰 A streaming hop through OpenAI's door,
Where text flows raw, and images soar,
Content converts without a fuss,
Events cascade, delighting us! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: improving OpenAI message content compatibility by fixing how MCP content is serialized and adding streaming support.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

src/mcp_agent/workflows/llm/augmented_llm_openai.py (1)

598-619: 💤 Low value

generate_stream fallback implementation is correct, but only TEXT_DELTA and COMPLETE events are emitted.

Tool calls are fully executed inside generate() before this method runs, so callers listening for TOOL_USE_START/TOOL_USE_END/TOOL_RESULT/ITERATION_* events will receive nothing. Since this is an intentional non-streaming fallback (the docstring calls this out), consider adding a comment or TODO to signal the gap to future implementors of true streaming.

💡 Suggested TODO

 async def generate_stream(
     self,
     message: MessageTypes,
     request_params: RequestParams | None = None,
 ) -> AsyncIterator[StreamEvent]:
     """
     Emit stream events using the non-streaming OpenAI generation path.

     OpenAI-native token streaming is not implemented here yet, but this keeps
     the provider concrete and gives callers a consistent event interface.
+
+    Note: Only TEXT_DELTA and COMPLETE events are emitted. Tool-use and
+    iteration events (TOOL_USE_START, TOOL_USE_END, TOOL_RESULT, ITERATION_*)
+    are not emitted because generate() executes tool calls synchronously.
+    # TODO: Replace with true streaming using client.chat.completions.create(stream=True)
     """

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/mcp_agent/workflows/llm/augmented_llm_openai.py` around lines 598 - 619,
The generate_stream fallback in augmented_llm_openai.py (function
generate_stream) only emits TEXT_DELTA and COMPLETE events and therefore does
not emit TOOL_USE_START/TOOL_USE_END/TOOL_RESULT or ITERATION_* events because
tool calls are fully executed inside generate(); add a clear TODO/comment at the
top of generate_stream explaining this limitation (that this is a non-streaming
fallback and tool/iteration events are not emitted) and reference that true
streaming should implement OpenAI-native token streaming to emit those events,
so future implementors know where to extend behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/mcp_agent/workflows/llm/augmented_llm_openai.py`:
- Around line 598-619: The generate_stream fallback in augmented_llm_openai.py
(function generate_stream) only emits TEXT_DELTA and COMPLETE events and
therefore does not emit TOOL_USE_START/TOOL_USE_END/TOOL_RESULT or ITERATION_*
events because tool calls are fully executed inside generate(); add a clear
TODO/comment at the top of generate_stream explaining this limitation (that this
is a non-streaming fallback and tool/iteration events are not emitted) and
reference that true streaming should implement OpenAI-native token streaming to
emit those events, so future implementors know where to extend behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4aa03b3a-3ab8-48d4-8437-1ae41ef57551

📥 Commits

Reviewing files that changed from the base of the PR and between f62d849 and 2966c39.

📒 Files selected for processing (2)

• src/mcp_agent/workflows/llm/augmented_llm_openai.py
• tests/workflows/llm/test_augmented_llm_openai.py