Implementation:Cohere ai Cohere python Message Union

Knowledge Sources	Cohere Python SDK
Domains	SDK, Chat
Last Updated	2026-02-15 14:00 GMT

Overview

Message is a discriminated union type representing the different message roles in a Cohere chat conversation: ChatbotMessage, SystemMessage, UserMessage, and ToolMessage.

Description

The Message type is defined as an annotated union of four Pydantic models, discriminated by the role field. Each variant corresponds to a different participant in a chat conversation:

• ChatbotMessage (role="CHATBOT") -- Represents a response from the chatbot, containing a message string and optional tool_calls.
• SystemMessage (role="SYSTEM") -- Represents a system prompt, containing a message string and optional tool_calls.
• UserMessage (role="USER") -- Represents a user input, containing a message string and optional tool_calls.
• ToolMessage (role="TOOL") -- Represents tool execution results, containing optional tool_results.

All variants extend UncheckedBaseModel and allow extra fields. The union uses UnionMetadata with discriminant="role" for efficient deserialization.

Usage

Use the Message type when constructing or processing chat history for the Cohere chat API. Messages represent the conversational context passed to the model, enabling multi-turn conversations with different participant roles. This type is used in the chat_history field of chat requests and responses.

Code Reference

Source Location

• Repository: Cohere Python SDK
• File: src/cohere/types/message.py

Signature

class ChatbotMessage(UncheckedBaseModel):
    role: typing.Literal["CHATBOT"] = "CHATBOT"
    message: str
    tool_calls: typing.Optional[typing.List[ToolCall]] = None

class SystemMessage(UncheckedBaseModel):
    role: typing.Literal["SYSTEM"] = "SYSTEM"
    message: str
    tool_calls: typing.Optional[typing.List[ToolCall]] = None

class UserMessage(UncheckedBaseModel):
    role: typing.Literal["USER"] = "USER"
    message: str
    tool_calls: typing.Optional[typing.List[ToolCall]] = None

class ToolMessage(UncheckedBaseModel):
    role: typing.Literal["TOOL"] = "TOOL"
    tool_results: typing.Optional[typing.List[ToolResult]] = None

Message = typing_extensions.Annotated[
    typing.Union[ChatbotMessage, SystemMessage, UserMessage, ToolMessage],
    UnionMetadata(discriminant="role"),
]

Import

from cohere.types import (
    ChatbotMessage,
    SystemMessage,
    UserMessage,
    ToolMessage,
)
# The Message union type itself:
from cohere.types.message import Message

I/O Contract

ChatbotMessage Fields

Field	Type	Required	Default	Description
role	Literal["CHATBOT"]	Yes	"CHATBOT"	Discriminator field identifying this as a chatbot message.
message	str	Yes	--	The chatbot's response text.
tool_calls	Optional[List[ToolCall]]	No	None	Tool calls generated by the chatbot.

SystemMessage Fields

Field	Type	Required	Default	Description
role	Literal["SYSTEM"]	Yes	"SYSTEM"	Discriminator field identifying this as a system message.
message	str	Yes	--	The system prompt text.
tool_calls	Optional[List[ToolCall]]	No	None	Tool calls associated with the system message.

UserMessage Fields

Field	Type	Required	Default	Description
role	Literal["USER"]	Yes	"USER"	Discriminator field identifying this as a user message.
message	str	Yes	--	The user's input text.
tool_calls	Optional[List[ToolCall]]	No	None	Tool calls associated with the user message.

ToolMessage Fields

Field	Type	Required	Default	Description
role	Literal["TOOL"]	Yes	"TOOL"	Discriminator field identifying this as a tool message.
tool_results	Optional[List[ToolResult]]	No	None	Results from tool executions.

Usage Examples

import cohere
from cohere.types import ChatbotMessage, SystemMessage, UserMessage

client = cohere.Client(api_key="YOUR_API_KEY")

# Build a chat history with different message roles
chat_history = [
    SystemMessage(message="You are a helpful assistant."),
    UserMessage(message="What is the capital of France?"),
    ChatbotMessage(message="The capital of France is Paris."),
]

# Use chat_history in a follow-up request
response = client.chat(
    model="command-r-plus",
    message="What about Germany?",
    chat_history=chat_history,
)

print(response.text)

# Access chat history from the response
if response.chat_history:
    for msg in response.chat_history:
        if hasattr(msg, "message"):
            print(f"[{msg.role}] {msg.message}")

Related Pages

• Environment:Cohere_ai_Cohere_python_Python_SDK_Runtime