Class ChatDocument

langroid/agent/chat_document.py:127–571

Represents a message in a conversation among agents. All responders of an agent have signature ChatDocument -> ChatDocument (modulo None, str, etc), and so does the Task.run() method. Attributes: oai_tool_calls (Optional[List[OpenAIToolCall]]): Tool-calls from a

class ChatDocument(Document):
    """
    Represents a message in a conversation among agents. All responders of an agent
    have signature ChatDocument -> ChatDocument (modulo None, str, etc),
    and so does the Task.run() method.

    Attributes:
        oai_tool_calls (Optional[List[OpenAIToolCall]]):
            Tool-calls from an OpenAI-compatible API
        oai_tool_id2results (Optional[OrderedDict[str, str]]):
            Results of tool-calls from OpenAI (dict is a map of tool_id -> result)
        oai_tool_choice: ToolChoiceTypes | Dict[str, str]: Param controlling how the
            LLM should choose tool-use in its response
            (auto, none, required, or a specific tool)
        function_call (Optional[LLMFunctionCall]):
            Function-call from an OpenAI-compatible API
                (deprecated by OpenAI, in favor of tool-calls)
        tool_messages (List[ToolMessage]): Langroid ToolMessages extracted from
            - `content` field (via JSON parsing),
            - `oai_tool_calls`, or
            - `function_call`
        metadata (ChatDocMetaData): Metadata for the message, e.g. sender, recipient.
        attachment (None | ChatDocAttachment): Any additional data attached.
    """

    reasoning: str = ""  # reasoning produced by a reasoning LLM
    content_any: Any = None  # to hold arbitrary data returned by responders
    # Original LLM response text including inline thought signatures
    # (e.g. <thinking>...</thinking>). Only populated when reasoning was
    # extracted from inline tags in the message text. Used by to_LLMMessage()
    # to preserve thought signatures in message history, which is critical
    # for models like Gemini 3 Flash and Amazon Nova that rely on seeing
    # their own thought tags in context to maintain reasoning ability.
    content_with_reasoning: Optional[str] = None
    files: List[FileAttachment] = []  # list of file attachments
    oai_tool_calls: Optional[List[OpenAIToolCall]] = None
    oai_tool_id2result: Optional[OrderedDict[str, str]] = None
    oai_tool_choice: ToolChoiceTypes | Dict[str, Dict[str, str] | str] = "auto"
    function_call: Optional[LLMFunctionCall] = None
    # tools that are explicitly added by agent response/handler,
    # or tools recognized in the ChatDocument as handle-able tools
    tool_messages: List[ToolMessage] = []
    # all known tools in the msg that are in an agent's llm_tools_known list,
    # even if non-used/handled
    # (the list is populated by Agent.has_tool_message_attempt())
    all_tool_messages: Optional[List[ToolMessage]] = None
    # ID of the agent that populated all_tool_messages (for cache validity)
    all_tool_messages_agent_id: Optional[str] = None

    metadata: ChatDocMetaData
    attachment: None | ChatDocAttachment = None

    def __init__(self, **data: Any):
        super().__init__(**data)
        ObjectRegistry.register_object(self)

    @property
    def parent(self) -> Optional["ChatDocument"]: