Implementation:Cohere ai Cohere python ChatMessageV2 Union

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

Overview

ChatMessageV2 is a discriminated union type that represents a single message in a V2 chat conversation, resolved to one of four role-specific variants: user, assistant, system, or tool.

Description

The ChatMessageV2 union is composed of four concrete message classes, each corresponding to a chat role:

• UserChatMessageV2 -- A message from the user, containing a role literal "user" and content of type UserMessageV2Content.
• AssistantChatMessageV2 -- A message from the assistant, containing a role literal "assistant", optional tool_calls (list of ToolCallV2), optional tool_plan (str), optional content of type AssistantMessageV2Content, and optional citations (list of Citation).
• SystemChatMessageV2 -- A system-level message, containing a role literal "system" and content of type SystemMessageV2Content.
• ToolChatMessageV2 -- A tool result message, containing a role literal "tool", a required tool_call_id (str), and content of type ToolMessageV2Content.

The union is discriminated on the role field, meaning the value of role determines which variant is deserialized.

Usage

Use ChatMessageV2 when constructing the messages parameter for the Cohere V2 chat API. Each element in the messages list should be one of the four variant types. This union enables type-safe multi-turn conversations with tool use, system prompts, and citation tracking.

Code Reference

Source Location

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

Signature

class UserChatMessageV2(UncheckedBaseModel):
    role: typing.Literal["user"] = "user"
    content: UserMessageV2Content

class AssistantChatMessageV2(UncheckedBaseModel):
    role: typing.Literal["assistant"] = "assistant"
    tool_calls: typing.Optional[typing.List[ToolCallV2]] = None
    tool_plan: typing.Optional[str] = None
    content: typing.Optional[AssistantMessageV2Content] = None
    citations: typing.Optional[typing.List[Citation]] = None

class SystemChatMessageV2(UncheckedBaseModel):
    role: typing.Literal["system"] = "system"
    content: SystemMessageV2Content

class ToolChatMessageV2(UncheckedBaseModel):
    role: typing.Literal["tool"] = "tool"
    tool_call_id: str
    content: ToolMessageV2Content

ChatMessageV2 = typing_extensions.Annotated[
    typing.Union[UserChatMessageV2, AssistantChatMessageV2, SystemChatMessageV2, ToolChatMessageV2],
    UnionMetadata(discriminant="role"),
]

Import

from cohere.types import ChatMessageV2
from cohere.types.chat_message_v2 import (
    UserChatMessageV2,
    AssistantChatMessageV2,
    SystemChatMessageV2,
    ToolChatMessageV2,
)

I/O Contract

UserChatMessageV2 Fields

Field	Type	Required	Description
role	Literal["user"]	Yes (default: "user")	Role discriminator, always "user".
content	UserMessageV2Content	Yes	The content of the user message.

AssistantChatMessageV2 Fields

Field	Type	Required	Description
role	Literal["assistant"]	Yes (default: "assistant")	Role discriminator, always "assistant".
tool_calls	Optional[List[ToolCallV2]]	No	Tool calls made by the assistant.
tool_plan	Optional[str]	No	The assistant's plan for tool usage.
content	Optional[AssistantMessageV2Content]	No	The text content of the assistant message.
citations	Optional[List[Citation]]	No	Citations linking generated text to sources.

SystemChatMessageV2 Fields

Field	Type	Required	Description
role	Literal["system"]	Yes (default: "system")	Role discriminator, always "system".
content	SystemMessageV2Content	Yes	The content of the system message.

ToolChatMessageV2 Fields

Field	Type	Required	Description
role	Literal["tool"]	Yes (default: "tool")	Role discriminator, always "tool".
tool_call_id	str	Yes	The ID of the tool call this message responds to.
content	ToolMessageV2Content	Yes	The content returned by the tool.

Usage Examples

from cohere.types.chat_message_v2 import (
    UserChatMessageV2,
    AssistantChatMessageV2,
    SystemChatMessageV2,
    ToolChatMessageV2,
)

# Build a multi-turn conversation with different roles
messages = [
    SystemChatMessageV2(content="You are a helpful assistant."),
    UserChatMessageV2(content="What is the weather in Boston?"),
    AssistantChatMessageV2(
        content="Let me check the weather for you.",
        tool_calls=[...],
        tool_plan="I will call the weather API.",
    ),
    ToolChatMessageV2(
        tool_call_id="call_abc123",
        content="The weather in Boston is 45F and cloudy.",
    ),
]

# Use with the V2 chat endpoint
response = client.chat(
    model="command-a-03-2025",
    messages=messages,
)

Related Pages

• Environment:Cohere_ai_Cohere_python_Python_SDK_Runtime