💬 消息体系

class BaseMessage(Serializable):
    """所有消息的抽象基类。消息是 chat model 的输入和输出。"""

    content: str | list[str | dict[Any, Any]]
    """消息内容。可以是纯字符串，也可以是多模态内容列表（文本/图片/工具结果）"""

    additional_kwargs: dict[Any, Any] = Field(default_factory=dict)
    """附加载荷。例如模型厂商特有的原始 tool_calls 编码"""

    response_metadata: dict[Any, Any] = Field(default_factory=dict)
    """响应元数据。例如 token 计数、模型名、响应头"""

    type: str
    """消息类型标识，用于反序列化时识别（如 "human"/"ai"/"system"）"""

    name: str | None = None
    """可选的可读名称"""

    id: str | None = Field(default=None, coerce_numbers_to_str=True)
    """消息唯一 ID，用于追踪和消息去重"""

class AIMessage(BaseMessage):
    """AI 返回的消息。代表模型的输出。"""

    tool_calls: list[ToolCall] = Field(default_factory=list)
    """工具调用列表 —— Agent 的"行动指令"就在这里。每个 ToolCall 含 name/args/id"""

    invalid_tool_calls: list[InvalidToolCall] = Field(default_factory=list)
    """解析失败的工具调用（如模型输出了格式错误的 JSON）"""

    usage_metadata: UsageMetadata | None = None
    """token 用量元数据（输入/输出/缓存 token 数），用于计费和监控"""

    type: Literal["ai"] = "ai"
    """类型固定为 "ai"，用于反序列化识别"""

# pip install langchain
from langchain_core.messages import (
    HumanMessage, AIMessage, SystemMessage, ToolMessage,
)

# ① SystemMessage —— 设定人设/规则
system = SystemMessage(content="你是一个天气助手，可以使用工具查天气。")

# ② HumanMessage —— 用户提问
user = HumanMessage(content="北京今天天气怎么样？")

# ③ AIMessage —— 模型回复，【带 tool_calls】表示要调工具
ai = AIMessage(
    content="",  # 可能没有文字内容
    tool_calls=[{
        "name": "search_weather",      # 工具名
        "args": {"location": "北京"},   # 参数
        "id": "call_abc123",           # 这次调用的唯一 ID
    }],
)

# ④ 应用层执行工具（这里假装执行）
result = '{"temp": 25, "weather": "晴"}'

# ⑤ ToolMessage —— 把结果喂回去，必须带 tool_call_id
tool_msg = ToolMessage(
    content=result,
    tool_call_id="call_abc123",   # 和上面 ai.tool_calls[0]["id"] 对应！
)

# ⑥ AIMessage —— 模型基于工具结果，给出最终回答（无 tool_calls = 循环结束）
final = AIMessage(content="北京今天 25 度，晴天。")

# 完整的一次 Agent 往返消息序列：
messages = [system, user, ai, tool_msg, final]
for m in messages:
    print(f"[{m.type:8}] {m.content[:40] if m.content else '(空)'}"
          + (f"  → tool_calls={m.tool_calls}" if hasattr(m, 'tool_calls') and m.tool_calls else ""))

# 输出：
# [system  ] 你是一个天气助手，可以使用工具查天气。
# [human   ] 北京今天天气怎么样？
# [ai      ] (空)  → tool_calls=[{'name': 'search_weather', ...}]
# [tool    ] {"temp": 25, "weather": "晴"}
# [ai      ] 北京今天 25 度，晴天。

from langchain_core.messages import HumanMessage

# content 是 list，混合文本和图片
msg = HumanMessage(content=[
    {"type": "text", "text": "这张图里是什么？"},
    {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}},
])
# 大多数主流 chat model 的 .invoke([msg]) 都能处理