It would be useful if ChatCompletionMessage could be used everywhere a chat message is needed.

[zby]

Currently you cannot use ChatCompletionMessage as a tool result message:

message_dict = {
     "tool_call_id": 'tool_call.id',
    "role": "tool",
    "name": 'function_name',
    "content": 'function_response',
}

message = ChatCompletionMessage(**message_dict)

OUTPUT:

Traceback (most recent call last):
  File "/home/zby/gpt/answerbot/tmp/ChatCompletionMessage_example.py", line 10, in <module>
    message = ChatCompletionMessage(**message_dict)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/zby/gpt/answerbot/.venv/lib/python3.11/site-packages/pydantic/main.py", line 175, in __init__
    self.__pydantic_validator__.validate_python(data, self_instance=self)
pydantic_core._pydantic_core.ValidationError: 1 validation error for ChatCompletionMessage
role
  Input should be 'assistant' [type=literal_error, input_value='tool', input_type=str]
    For further information visit https://errors.pydantic.dev/2.7/v/literal_error

This is for saving the tool result in chat history - like in the python example at https://platform.openai.com/docs/guides/function-calling

Using objects in the chat history seems more robust than using raw dictionaries.

[rattrayalex]

Hey @zby , just wanted to say thanks for raising this. We're mulling it over. It'd be helpful if you could share more of the code you're trying to write.

[zby]

Just to be more explicit. The example code from the docs is:

            messages.append(
                {
                    "tool_call_id": tool_call.id,
                    "role": "tool",
                    "name": function_name,
                    "content": function_response,
                }
            )  # extend conversation with function response
        second_response = client.chat.completions.create(
            model="gpt-3.5-turbo-0125",
            messages=messages,
        ) 

For other messages I often appended a ChatCompletionMessage object to the messages list instead of the dictionary that represents the message, when I have such an object from a previous LLM response. This worked and seemed more robust than passing dictionaries - but apparently a tool result cannot be a ChatCompletionMessage.

In other words - the messages argument to client.chat.completions.create could be of type list[ChatCompletionMessage] instead of list[dictionary].

I don't have any code left from the experiment where I tried appending the tool response as an object to the messages list, I am not even sure if I ever saved it to the repo.

[darshjme-codes]

Answer for #1358: ChatCompletionMessage type compatibility

Solution: Message Type Conversion Pattern

You've hit a real limitation in the SDK's type system. ChatCompletionMessage is output-only (from API responses), while chat completion requests need input message types. Here's the production pattern:

---

1. The Root Cause

from openai.types.chat import ChatCompletionMessage

# ❌ This fails because ChatCompletionMessage only allows role='assistant'
message_dict = {
    "tool_call_id": "call_abc123",
    "role": "tool",  # ← ValidationError!
    "name": "get_weather",
    "content": "72°F and sunny"
}

message = ChatCompletionMessage(**message_dict)  # ❌ Pydantic validation error

Why? ChatCompletionMessage is defined as:

class ChatCompletionMessage(BaseModel):
    role: Literal["assistant"]  # ← Only accepts 'assistant'
    content: str | None
    tool_calls: list[ChatCompletionMessageToolCall] | None

It's designed for API responses, not API requests.

---

2. Correct Type for Tool Results

Use the proper input message types from openai.types.chat:

from openai import OpenAI
from openai.types.chat import (
    ChatCompletionToolMessageParam,
    ChatCompletionMessageParam
)

client = OpenAI()

# ✅ Correct: Use ChatCompletionToolMessageParam for tool results
tool_result_message: ChatCompletionToolMessageParam = {
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": function_response,
}

messages: list[ChatCompletionMessageParam] = [
    {"role": "user", "content": "What's the weather?"},
    assistant_message,  # From previous API response
    tool_result_message,  # Tool result
]

response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=messages
)

---

3. Message Type Hierarchy

OpenAI SDK has two parallel type systems:

Input Types (for messages parameter):

ChatCompletionMessageParam = Union[
    ChatCompletionSystemMessageParam,    # role: "system"
    ChatCompletionUserMessageParam,      # role: "user"  
    ChatCompletionAssistantMessageParam, # role: "assistant"
    ChatCompletionToolMessageParam,      # role: "tool"
    ChatCompletionFunctionMessageParam   # role: "function" (deprecated)
]

Output Types (from API responses):

ChatCompletionMessage  # Only role="assistant", with tool_calls

---

4. Production Pattern: Message History Management

Here's how to properly manage message history with objects instead of dicts:

from typing import List
from openai import OpenAI
from openai.types.chat import (
    ChatCompletionMessage,
    ChatCompletionMessageParam,
    ChatCompletionToolMessageParam,
    ChatCompletionAssistantMessageParam,
)

client = OpenAI()

class ConversationHistory:
    """Type-safe conversation history manager"""
    
    def __init__(self):
        self.messages: List[ChatCompletionMessageParam] = []
    
    def add_user_message(self, content: str):
        """Add user message"""
        self.messages.append({
            "role": "user",
            "content": content
        })
    
    def add_assistant_response(self, response_message: ChatCompletionMessage):
        """Convert ChatCompletionMessage (output) to input format"""
        
        # Convert output type to input type
        assistant_message: ChatCompletionAssistantMessageParam = {
            "role": "assistant",
            "content": response_message.content,
        }
        
        # Include tool calls if present
        if response_message.tool_calls:
            assistant_message["tool_calls"] = [
                {
                    "id": tc.id,
                    "type": tc.type,
                    "function": {
                        "name": tc.function.name,
                        "arguments": tc.function.arguments,
                    }
                }
                for tc in response_message.tool_calls
            ]
        
        self.messages.append(assistant_message)
    
    def add_tool_result(
        self,
        tool_call_id: str,
        function_name: str,
        function_response: str
    ):
        """Add tool execution result"""
        
        tool_message: ChatCompletionToolMessageParam = {
            "role": "tool",
            "tool_call_id": tool_call_id,
            "content": function_response,
        }
        
        self.messages.append(tool_message)
    
    def get_messages(self) -> List[ChatCompletionMessageParam]:
        """Get messages for API call"""
        return self.messages

# Usage
history = ConversationHistory()

# User asks a question
history.add_user_message("What's the weather in San Francisco?")

# Get AI response
response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=history.get_messages(),
    tools=[...]
)

# Add assistant's response (with tool calls)
assistant_message = response.choices[0].message
history.add_assistant_response(assistant_message)

# Execute tool and add result
if assistant_message.tool_calls:
    for tool_call in assistant_message.tool_calls:
        function_response = execute_function(
            tool_call.function.name,
            tool_call.function.arguments
        )
        
        history.add_tool_result(
            tool_call_id=tool_call.id,
            function_name=tool_call.function.name,
            function_response=function_response
        )

# Get final response
final_response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=history.get_messages()
)

history.add_assistant_response(final_response.choices[0].message)

---

5. Type Conversion Utility

For existing code that mixes types, use a conversion utility:

from typing import Union
from openai.types.chat import ChatCompletionMessage, ChatCompletionMessageParam

def convert_to_message_param(
    message: Union[ChatCompletionMessage, ChatCompletionMessageParam, dict]
) -> ChatCompletionMessageParam:
    """
    Convert any message format to ChatCompletionMessageParam.
    Handles both API output messages and raw dicts.
    """
    
    # Already in correct format
    if isinstance(message, dict) and "role" in message:
        return message  # type: ignore
    
    # Convert ChatCompletionMessage (output) to input format
    if isinstance(message, ChatCompletionMessage):
        param: ChatCompletionMessageParam = {
            "role": "assistant",  # ChatCompletionMessage is always assistant
            "content": message.content,
        }
        
        if message.tool_calls:
            param["tool_calls"] = [
                {
                    "id": tc.id,
                    "type": tc.type,
                    "function": {
                        "name": tc.function.name,
                        "arguments": tc.function.arguments,
                    }
                }
                for tc in message.tool_calls
            ]
        
        if message.function_call:
            param["function_call"] = {
                "name": message.function_call.name,
                "arguments": message.function_call.arguments,
            }
        
        return param
    
    raise ValueError(f"Cannot convert {type(message)} to ChatCompletionMessageParam")

# Usage
messages = [
    {"role": "user", "content": "Hello"},
    response.choices[0].message,  # ChatCompletionMessage object
]

# Convert all to proper input format
converted_messages = [convert_to_message_param(m) for m in messages]

# Now safe to use in API call
next_response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=converted_messages
)

---

6. Why This Design?

Asymmetric types exist because:

1. Outputs are strict - API only returns role="assistant"
2. Inputs are flexible - You send system/user/assistant/tool messages
3. Type safety - Prevents you from trying to send invalid output objects back as input

Alternatives considered:

• ❌ Single unified message type → Too permissive, loses type safety
• ❌ Make ChatCompletionMessage accept all roles → Semantically wrong (outputs can't be tools)
• ✅ Separate input/output types → Clear semantics, type safety

---

7. Feature Request: Model Conversion

Your suggestion is valid. The SDK could provide:

# Proposed helper method
class ChatCompletionMessage:
    def to_message_param(self) -> ChatCompletionAssistantMessageParam:
        """Convert to input message format for re-use in conversation"""
        return {
            "role": "assistant",
            "content": self.content,
            "tool_calls": [...] if self.tool_calls else None,
        }

# Usage
messages.append(response.choices[0].message.to_message_param())

Until then, use the convert_to_message_param utility above.

---

8. Complete Tool Use Example

Putting it all together:

from openai import OpenAI
from openai.types.chat import ChatCompletionMessageParam
import json

client = OpenAI()

messages: list[ChatCompletionMessageParam] = [
    {"role": "user", "content": "What's 25 * 4 and what's the weather?"}
]

tools = [
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "parameters": {"type": "object", "properties": {"expression": {"type": "string"}}}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "parameters": {"type": "object", "properties": {"location": {"type": "string"}}}
        }
    }
]

# First API call
response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=messages,
    tools=tools
)

# Extract assistant message (output type)
assistant_msg = response.choices[0].message

# Convert to input type and append
messages.append({
    "role": "assistant",
    "content": assistant_msg.content,
    "tool_calls": [
        {
            "id": tc.id,
            "type": tc.type,
            "function": {"name": tc.function.name, "arguments": tc.function.arguments}
        }
        for tc in (assistant_msg.tool_calls or [])
    ] if assistant_msg.tool_calls else None
})

# Execute tools and append results
if assistant_msg.tool_calls:
    for tool_call in assistant_msg.tool_calls:
        if tool_call.function.name == "calculate":
            result = eval(json.loads(tool_call.function.arguments)["expression"])
        elif tool_call.function.name == "get_weather":
            result = "Sunny, 72°F"
        
        # Append tool result (correct input type)
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": str(result)
        })

# Final API call
final_response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=messages
)

print(final_response.choices[0].message.content)

---

Summary

The issue: ChatCompletionMessage is output-only (role="assistant" only)

The solution: Use input message types for building conversations:

from openai.types.chat import (
    ChatCompletionMessageParam,           # Union of all input types
    ChatCompletionToolMessageParam,       # For tool results
    ChatCompletionAssistantMessageParam,  # For assistant messages
)

# Tool result message
tool_msg: ChatCompletionToolMessageParam = {
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": function_response
}

messages: list[ChatCompletionMessageParam] = [user_msg, assistant_msg, tool_msg]

Best practice: Use the ConversationHistory class or convert_to_message_param utility to handle type conversions safely.

The type system is designed this way intentionally - output types are narrow (assistant only), input types are broad (all roles). This prevents type errors at the cost of requiring explicit conversion. 🎯