Add MessageConverter protocol for multipart converters

[StreetLamb]

Summary by CodeRabbit

• Refactor

  • Standardized method naming conventions for message conversion across all supported providers, improving consistency and maintainability.
  • Introduced a unified interface for message converters to streamline message handling.
  • Updated internal logic to use new method names for converting messages to provider-compatible formats.

• Tests

  • Updated test suites to use the new standardized method names, ensuring continued reliability of message conversion functionality.

[coderabbitai]

Walkthrough

This change introduces a generic MessageConverter protocol for message conversion and refactors all provider-specific converters (Anthropic, Azure, Bedrock, Google, OpenAI) to inherit from it. All converter methods are renamed to a consistent from_* naming scheme. The corresponding usage and tests are updated to use the new method names and interfaces.

Changes

Files/Groups	Change Summary
src/mcp_agent/workflows/llm/multipart_converter.py	Adds a generic MessageConverter protocol/interface for standardizing message conversion methods.
src/mcp_agent/workflows/llm/multipart_converter_anthropic.py src/mcp_agent/workflows/llm/multipart_converter_azure.py src/mcp_agent/workflows/llm/multipart_converter_bedrock.py src/mcp_agent/workflows/llm/multipart_converter_google.py src/mcp_agent/workflows/llm/multipart_converter_openai.py	Refactor each provider's converter class to inherit from MessageConverter; rename all conversion methods to from_* convention; update method signatures to use provider-specific types.
src/mcp_agent/workflows/llm/augmented_llm_anthropic.py src/mcp_agent/workflows/llm/augmented_llm_azure.py src/mcp_agent/workflows/llm/augmented_llm_bedrock.py src/mcp_agent/workflows/llm/augmented_llm_google.py src/mcp_agent/workflows/llm/augmented_llm_openai.py	Update usage of converter methods in each LLM class to use the new from_mixed_messages method.
tests/utils/test_multipart_converter_anthropic.py tests/utils/test_multipart_converter_azure.py tests/utils/test_multipart_converter_bedrock.py tests/utils/test_multipart_converter_google.py tests/utils/test_multipart_converter_openai.py	Update all test invocations to use the renamed from_* converter methods.

Suggested reviewers

• saqadri

Poem

A rabbit hops from file to file,
Refactoring code with a clever smile.
"From" is the word, converters align,
Each provider now shares a design.
Tests and logic, all in sync—
This code refactor’s quick as a wink!
🐇✨

---

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 37c8d2e and e9a778d.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (16)

• src/mcp_agent/workflows/llm/augmented_llm_anthropic.py (1 hunks)
• src/mcp_agent/workflows/llm/augmented_llm_azure.py (1 hunks)
• src/mcp_agent/workflows/llm/augmented_llm_bedrock.py (1 hunks)
• src/mcp_agent/workflows/llm/augmented_llm_google.py (1 hunks)
• src/mcp_agent/workflows/llm/augmented_llm_openai.py (1 hunks)
• src/mcp_agent/workflows/llm/multipart_converter.py (1 hunks)
• src/mcp_agent/workflows/llm/multipart_converter_anthropic.py (9 hunks)
• src/mcp_agent/workflows/llm/multipart_converter_azure.py (8 hunks)
• src/mcp_agent/workflows/llm/multipart_converter_bedrock.py (8 hunks)
• src/mcp_agent/workflows/llm/multipart_converter_google.py (8 hunks)
• src/mcp_agent/workflows/llm/multipart_converter_openai.py (13 hunks)
• tests/utils/test_multipart_converter_anthropic.py (8 hunks)
• tests/utils/test_multipart_converter_azure.py (10 hunks)
• tests/utils/test_multipart_converter_bedrock.py (10 hunks)
• tests/utils/test_multipart_converter_google.py (12 hunks)
• tests/utils/test_multipart_converter_openai.py (9 hunks)

🧰 Additional context used

🧠 Learnings (13)

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

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/src/{tasks,workflows}/*.py : Use mcp-agent's Agent abstraction for ALL LLM interactions, including quality evaluation, to ensure consistent tool access, logging, and error handling.

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

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/src/{tasks,workflows}/*.py : Use mcp-agent's Agent abstraction for ALL LLM interactions, including quality evaluation, to ensure consistent tool access, logging, and error handling.

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

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/src/{tasks,workflows}/*.py : Use mcp-agent's Agent abstraction for ALL LLM interactions, including quality evaluation, to ensure consistent tool access, logging, and error handling.

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

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/src/{tasks,workflows}/*.py : Use mcp-agent's Agent abstraction for ALL LLM interactions, including quality evaluation, to ensure consistent tool access, logging, and error handling.

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

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/src/{tasks,workflows}/*.py : Use mcp-agent's Agent abstraction for ALL LLM interactions, including quality evaluation, to ensure consistent tool access, logging, and error handling.

tests/utils/test_multipart_converter_anthropic.py (1)

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/**/test_basic.py : Automated tests must validate multi-turn state persistence, requirement tracking, quality control pipeline, context consolidation, and research metrics collection.

tests/utils/test_multipart_converter_openai.py (1)

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/**/test_basic.py : Automated tests must validate multi-turn state persistence, requirement tracking, quality control pipeline, context consolidation, and research metrics collection.

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

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/src/{tasks,workflows}/*.py : Use mcp-agent's Agent abstraction for ALL LLM interactions, including quality evaluation, to ensure consistent tool access, logging, and error handling.

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

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/src/{tasks,workflows}/*.py : Use mcp-agent's Agent abstraction for ALL LLM interactions, including quality evaluation, to ensure consistent tool access, logging, and error handling.

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

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/src/{tasks,workflows}/*.py : Use mcp-agent's Agent abstraction for ALL LLM interactions, including quality evaluation, to ensure consistent tool access, logging, and error handling.

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

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/src/{tasks,workflows}/*.py : Use mcp-agent's Agent abstraction for ALL LLM interactions, including quality evaluation, to ensure consistent tool access, logging, and error handling.

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

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/src/{tasks,workflows}/*.py : Use mcp-agent's Agent abstraction for ALL LLM interactions, including quality evaluation, to ensure consistent tool access, logging, and error handling.

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

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-06-30T17:58:30.949Z
Learning: Applies to examples/usecases/reliable_conversation/src/{tasks,workflows}/*.py : Use mcp-agent's Agent abstraction for ALL LLM interactions, including quality evaluation, to ensure consistent tool access, logging, and error handling.

🧬 Code Graph Analysis (3)

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

src/mcp_agent/workflows/llm/multipart_converter_anthropic.py (2)

• AnthropicConverter (52-518)
• from_mixed_messages (489-518)

src/mcp_agent/workflows/llm/augmented_llm_google.py (2)

src/mcp_agent/workflows/llm/multipart_converter_google.py (2)

• GoogleConverter (40-380)
• from_mixed_messages (346-380)

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

• from_mixed_messages (23-25)

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

src/mcp_agent/workflows/llm/multipart_converter_azure.py (2)

• AzureConverter (53-369)
• from_mixed_messages (339-369)

🔇 Additional comments (45)

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

158-158: LGTM! Consistent method name refactoring.

The change from convert_mixed_messages_to_anthropic to from_mixed_messages aligns with the broader refactoring to standardize method naming across all provider converters. The functionality remains unchanged while improving interface consistency.

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

104-104: LGTM! Consistent method name refactoring.

The change from convert_mixed_messages_to_bedrock to from_mixed_messages follows the same standardization pattern applied across all provider converters. The refactoring maintains functionality while improving naming consistency.

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

156-156: LGTM! Consistent method name refactoring.

The change from convert_mixed_messages_to_azure to from_mixed_messages completes the consistent refactoring pattern across all provider converters. This standardizes the interface while preserving the original functionality.

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

185-185: All references to convert_mixed_messages_to_openai have been removed

The ripgrep search returned no matches, confirming that the old method name no longer exists in the codebase. Change is consistent with the refactoring and can be approved.

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

88-88: Approve: GoogleConverter method rename is consistent

The change from convert_mixed_messages_to_google to from_mixed_messages aligns with the refactoring applied to the OpenAI converter and maintains identical functionality.

Please manually verify that no references to the old method name remain by running:

rg "convert_mixed_messages_to_google" --type py

tests/utils/test_multipart_converter_azure.py (4)

31-31: LGTM! Test method calls updated to use new converter interface.

The test calls have been correctly updated from convert_to_azure to from_prompt_message_multipart, maintaining the same test logic while adapting to the new method naming convention.

Also applies to: 39-39, 48-48, 57-57, 69-69

---

78-78: LGTM! PromptMessage conversion method updated consistently.

The method call has been correctly updated from convert_prompt_message_to_azure to from_prompt_message, following the standardized naming pattern.

---

238-238: LGTM! Tool result conversion methods updated consistently.

All test calls have been properly updated from convert_tool_result_to_azure to from_tool_result, maintaining test coverage while adopting the new interface.

Also applies to: 247-247, 281-281, 294-294

---

262-262: LGTM! Tool results method rename follows the pattern.

The method call has been correctly updated from create_tool_results_message to from_tool_results, aligning with the from_* naming convention.

tests/utils/test_multipart_converter_openai.py (4)

30-30: LGTM! Test method calls updated consistently across all prompt message conversion tests.

All test calls have been correctly updated from convert_to_openai to from_prompt_message_multipart, maintaining the same test logic while adopting the new method naming convention.

Also applies to: 38-38, 49-49, 72-74

---

107-107: LGTM! PromptMessage conversion test updated consistently.

The method call has been properly updated from convert_prompt_message_to_openai to from_prompt_message, following the standardized naming pattern.

---

292-292: LGTM! Tool result conversion tests updated consistently.

All test calls have been correctly updated from convert_tool_result_to_openai to from_tool_result, preserving test coverage while adopting the new interface.

Also applies to: 301-301, 314-314

---

337-337: LGTM! Tool results conversion tests updated consistently.

The method calls have been properly updated from convert_function_results_to_openai to from_tool_results, maintaining the from_* naming convention established across the refactoring.

Also applies to: 356-356

tests/utils/test_multipart_converter_google.py (1)

31-31: LGTM! Test method calls updated to match new interface.

The test suite correctly adopts the new from_* method naming convention while preserving all existing test logic and coverage. This ensures the refactored GoogleConverter maintains the same behavior.

Also applies to: 47-47, 64-64, 83-83, 100-100, 118-118, 406-406, 424-424, 442-442, 467-467, 489-489, 512-512

tests/utils/test_multipart_converter_bedrock.py (1)

31-31: LGTM! Consistent test updates for BedrockConverter.

The test method calls have been systematically updated to use the new from_* naming convention, maintaining full test coverage while conforming to the new MessageConverter interface.

Also applies to: 39-39, 48-48, 59-59, 70-70, 262-262, 274-274, 285-285, 304-304, 327-327, 342-342

tests/utils/test_multipart_converter_anthropic.py (1)

31-31: LGTM! AnthropicConverter tests updated consistently.

All test method calls have been updated to use the new from_* naming convention, ensuring test coverage remains intact while adopting the standardized interface.

Also applies to: 39-39, 49-49, 61-61, 74-74, 85-85, 237-237, 249-249, 265-265

src/mcp_agent/workflows/llm/multipart_converter_google.py (5)

32-32: Good addition of MessageConverter import.

The import correctly brings in the new protocol interface that the class will inherit from.

---

40-45: Excellent protocol inheritance with proper type parameters.

The GoogleConverter now correctly inherits from MessageConverter[types.Content, types.Content], properly specifying the Google-specific message types while conforming to the standardized interface.

---

61-63: Method renamed consistently with protocol interface.

The method signature correctly matches the protocol definition and maintains the same functionality with the new standardized naming.

---

84-84: Consistent method renaming and internal call updates.

Both the method signature and the internal call have been properly updated to use the new naming convention, maintaining internal consistency.

Also applies to: 95-95

---

287-287: All method signatures and internal calls updated consistently.

The systematic renaming of all conversion methods to the from_* convention is well-executed, with all internal method calls properly updated to maintain functionality while adopting the new standardized interface.

Also applies to: 325-325, 340-340, 346-346, 366-366, 370-370

src/mcp_agent/workflows/llm/multipart_converter_bedrock.py (7)

30-30: Protocol import looks good.

The import of MessageConverter sets up the foundation for the standardized interface.

---

48-48: Excellent protocol inheritance implementation.

The class now properly inherits from MessageConverter[MessageUnionTypeDef, MessageUnionTypeDef], which standardizes the interface across all provider converters while maintaining Bedrock-specific type safety.

---

57-69: Method renamed consistently to follow from_* convention.

The rename from convert_to_bedrock to from_prompt_message_multipart aligns with the standardized naming scheme across all converters.

---

72-79: Method rename and internal call update executed properly.

Both the method name change and the internal call to from_prompt_message_multipart maintain consistency within the class.

---

231-246: Tool result conversion method properly renamed.

The from_tool_result naming is more intuitive and follows the established pattern.

---

249-269: Tool results message creation method renamed appropriately.

The from_tool_results name clearly indicates the method's purpose and input type.

---

272-302: Mixed messages conversion method with updated internal calls.

The method has been properly renamed and all internal calls use the new method names, maintaining consistency throughout the class.

src/mcp_agent/workflows/llm/multipart_converter_anthropic.py (5)

15-15: Proper imports for protocol implementation.

The addition of Message import and MessageConverter import provides the necessary types for the protocol inheritance.

Also applies to: 44-44

---

52-52: Well-typed protocol inheritance.

The MessageConverter[MessageParam, Message] inheritance uses appropriate Anthropic-specific types, ensuring type safety while conforming to the standardized interface.

---

68-104: Consistent method renaming with preserved functionality.

The from_prompt_message_multipart method maintains all original logic while adopting the standardized naming convention.

---

107-121: Method rename with proper internal call update.

Both the method rename and the internal call to from_prompt_message_multipart demonstrate consistent refactoring.

---

371-413: All remaining methods follow the standardized pattern.

The from_tool_result, from_tool_results, and from_mixed_messages methods all follow the new naming convention with properly updated internal calls.

Also applies to: 416-486, 489-518

src/mcp_agent/workflows/llm/multipart_converter_azure.py (5)

14-14: Added necessary imports for protocol implementation.

The ChatResponseMessage and MessageConverter imports support the enhanced type safety and protocol conformance.

Also applies to: 42-42

---

46-48: Excellent addition of type alias for Azure messages.

The AzureMessageParam union type improves code readability and provides a centralized definition for Azure-specific message types.

---

53-58: Well-structured protocol inheritance with Azure-specific types.

The multiline inheritance declaration is clean and uses appropriate Azure types for both input and output parameters.

---

66-103: Method renamed with preserved Azure-specific logic.

The from_prompt_message_multipart method maintains all Azure-specific handling (like assistant message restrictions) while adopting the standardized naming.

---

341-341: Improved return type annotation using the new type alias.

Using List[AzureMessageParam] instead of a generic list improves type safety and code clarity.

src/mcp_agent/workflows/llm/multipart_converter_openai.py (7)

10-15: Excellent enhancement of type imports.

The addition of specific OpenAI SDK types (ChatCompletionMessageParam, ChatCompletionUserMessageParam, etc.) significantly improves type safety over generic dictionaries.

---

43-45: Proper protocol inheritance with OpenAI-specific types.

The MessageConverter[ChatCompletionMessageParam, ChatCompletionMessage] inheritance provides strong typing while conforming to the standardized interface.

---

66-68: Method rename with improved return type annotation.

The change from returning generic dictionaries to ChatCompletionMessageParam provides better type safety and IDE support.

---

366-369: Significantly improved return type specificity.

The union return type Union[ChatCompletionToolMessageParam, Tuple[ChatCompletionToolMessageParam, list[ChatCompletionMessageParam]]] is much more precise than the previous generic approach.

---

387-391: Consistent use of specific OpenAI message classes.

Replacing generic dictionaries with ChatCompletionToolMessageParam instances provides compile-time type checking and better developer experience.

Also applies to: 421-423

---

443-446: Method renames with enhanced type annotations.

Both from_tool_results and from_mixed_messages now use specific OpenAI types in their signatures, improving overall type safety.

Also applies to: 478-480

---

30-48: MessageConverter protocol compliance confirmed
All LLM converters (Anthropic, Azure, Bedrock, Google, and OpenAI) implement the four required static methods (from_prompt_message_multipart, from_prompt_message, from_mixed_messages, and from_tool_results). No further changes are needed.

✨ Finishing Touches

• 📝 Generate Docstrings

---

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

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[saqadri]

Awesome, thank you for doing this! one question on adding a to_prompt_message to the MessageConverter protocol, but not urgent if we don't have a usecase for it yet.

[saqadri]

Do we want an API here for converting from provider message type to PromptMessage? i.e. a to_prompt_message?

[saqadri]

@StreetLamb can you please get this ready to be merged in. Probably just need to update uv.lock merge conflict but otherwise should be good as-is AFAICT