trading_agent.agent.messages

The messages of a conversation, in a form that does not depend on any model.

Each backend converts these into its own wire format, so the same conversation can move from Gemma to Qwen to Claude when the router changes backend.

Typical usage example:

call = ToolCall.new('get_time', {}) message = ConversationMessage.assistant('', [call])

Role

Bases: StrEnum

Who a message comes from.

ToolCall dataclass

ToolCall(call_id, name, arguments)

One request from the model to run a tool.

Attributes:

Name	Type	Description
call_id	str	An identifier that matches the call with its result. Ollama gives none, so it is created here when missing.
name	str	The tool's name.
arguments	dict[str, Any]	The arguments, as the model wrote them.

new classmethod

new(name, arguments)

Creates a tool call with a fresh identifier.

Parameters:

Name	Type	Description	Default
name	str	The tool's name.	required
arguments	dict[str, Any]	The arguments.	required

Returns:

Type	Description
ToolCall	The new call.

Source code in src/trading_agent/agent/messages.py

@classmethod
def new(cls, name: str, arguments: dict[str, Any]) -> Self:
    """Creates a tool call with a fresh identifier.

    Args:
        name (str): The tool's name.
        arguments (dict[str, Any]): The arguments.

    Returns:
        ToolCall: The new call.
    """
    return cls(call_id=uuid.uuid4().hex, name=name, arguments=arguments)

MessageImage dataclass

MessageImage(media_type, data)

A picture sent to the model, with a user message or a tool's result.

Attributes:

Name	Type	Description
media_type	str	The picture's media type, image/jpeg or image/png.
data	bytes	The encoded picture.

base64_data

base64_data()

The picture in base64, as the model APIs take it.

Returns:

Type	Description
str	The base64 text.

Source code in src/trading_agent/agent/messages.py

def base64_data(self) -> str:
    """The picture in base64, as the model APIs take it.

    Returns:
        str: The base64 text.
    """
    return base64.b64encode(self.data).decode('ascii')

ConversationMessage dataclass

ConversationMessage(role, text, tool_calls=(), tool_call_id=None, tool_name=None, is_error=False, image=None, images=(), reasoning='')

One message in a conversation.

Attributes:

Name	Type	Description
role	Role	Who the message comes from.
text	str	The message's text; may be empty for an assistant message that only calls tools.
tool_calls	tuple[ToolCall, ...]	The tools an assistant message asks to run.
tool_call_id	str | None	For a tool message, the identifier of the call it answers.
tool_name	str | None	For a tool message, the name of the tool that ran.
is_error	bool	For a tool message, whether the tool failed.
image	MessageImage | None	For a tool message, a picture the tool returned, or None.
images	tuple[MessageImage, ...]	For a user message, the pictures sent with it.
reasoning	str	For an assistant message, the model's visible thinking, which some servers, such as DeepSeek's, require to be sent back with the message.

user classmethod

user(text, images=())

Creates a user message.

Parameters:

Name	Type	Description	Default
text	str	What the user, or a trigger, says.	required
images	tuple[MessageImage, ...]	The pictures sent with it.	()

Returns:

Type	Description
ConversationMessage	The message.

Source code in src/trading_agent/agent/messages.py

@classmethod
def user(
    cls,
    text: str,
    images: tuple[MessageImage, ...] = (),
) -> Self:
    """Creates a user message.

    Args:
        text (str): What the user, or a trigger, says.
        images (tuple[MessageImage, ...]): The pictures sent with it.

    Returns:
        ConversationMessage: The message.
    """
    return cls(role=Role.USER, text=text, images=images)

assistant classmethod

assistant(text, tool_calls, reasoning='')

Creates an assistant message.

Parameters:

Name	Type	Description	Default
text	str	The model's text.	required
tool_calls	list[ToolCall]	The tools it asks to run.	required
reasoning	str	The model's visible thinking, or empty.	''

Returns:

Type	Description
ConversationMessage	The message.

Source code in src/trading_agent/agent/messages.py

@classmethod
def assistant(
    cls,
    text: str,
    tool_calls: list[ToolCall],
    reasoning: str = '',
) -> Self:
    """Creates an assistant message.

    Args:
        text (str): The model's text.
        tool_calls (list[ToolCall]): The tools it asks to run.
        reasoning (str): The model's visible thinking, or empty.

    Returns:
        ConversationMessage: The message.
    """
    return cls(
        role=Role.ASSISTANT,
        text=text,
        tool_calls=tuple(tool_calls),
        reasoning=reasoning,
    )

tool_result classmethod

tool_result(call, text, is_error, image=None)

Creates the message that carries a tool's result back to the model.

Parameters:

Name	Type	Description	Default
call	ToolCall	The call being answered.	required
text	str	The tool's output.	required
is_error	bool	Whether the tool failed.	required
image	MessageImage | None	A picture the tool returned, or None.	None

Returns:

Type	Description
ConversationMessage	The message.

Source code in src/trading_agent/agent/messages.py

@classmethod
def tool_result(
    cls,
    call: ToolCall,
    text: str,
    is_error: bool,
    image: MessageImage | None = None,
) -> Self:
    """Creates the message that carries a tool's result back to the model.

    Args:
        call (ToolCall): The call being answered.
        text (str): The tool's output.
        is_error (bool): Whether the tool failed.
        image (MessageImage | None): A picture the tool returned, or None.

    Returns:
        ConversationMessage: The message.
    """
    return cls(
        role=Role.TOOL,
        text=text,
        tool_call_id=call.call_id,
        tool_name=call.name,
        is_error=is_error,
        image=image,
    )