📐 Agent 数据模型

class AgentAction(Serializable):
    """代表 agent 要执行一个动作的请求。"""

    tool: str
    """要执行的工具名（如 "search_weather"）"""

    tool_input: str | dict[Any, Any]
    """传给工具的输入（如 {"city": "北京"}）"""

    log: str
    """附加日志信息。
    用途1：审计 LLM 到底预测了什么才得到这个 action。
    用途2：在后续迭代中展示给 LLM 看（含工具调用前的"思考"）。"""

    type: Literal["AgentAction"] = "AgentAction"
    """类型标识，用于反序列化"""

class AgentFinish(Serializable):
    """ActionAgent 的最终返回值。
    当 agent 到达停止条件时返回 AgentFinish。"""

    return_values: dict[Any, Any]
    """返回值字典。通常 {"output": 最终答案}"""

    log: str
    """完整 LLM 预测的日志（不只是解析出的答案）。
    例如 LLM 实际输出 "Final Answer: 2"，return_values={"output": "2"}，
    但 log 保留完整字符串供调试/观测。"""

    type: Literal["AgentFinish"] = "AgentFinish"

class AgentStep(Serializable):
    """执行一个 AgentAction 的结果。"""

    action: AgentAction
    """被执行的动作"""

    observation: Any
    """这个动作的结果（即工具返回值）"""

    @property
    def messages(self) -> Sequence[BaseMessage]:
        """这一步对应的等价消息序列（action → AIMessage，observation → ToolMessage）。"""
        return _convert_agent_observation_to_messages(self.action, self.observation)

# AgentAction.messages（agents.py:101）→ AIMessage（带 tool_calls）
# AgentStep.messages （agents.py:142）→ AIMessage + ToolMessage

# 也就是说：
AgentAction(tool="search", tool_input={"city":"北京"}, log="...")
#   ⇄  AIMessage(content="", tool_calls=[{name:"search", args:{"city":"北京"}}])

AgentStep(action=上述, observation="晴25度")
#   ⇄  [AIMessage(...tool_calls...), ToolMessage(content="晴25度")]

# 这意味着：Agent 的"历史步骤列表"
#   和 Chat 的"消息历史"是同一份信息的两种表示！
# 这就是为什么 LangGraph 能用 messages 列表承载整个 Agent 状态（见 LG1）。

from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个助手。可以使用工具：{tools}。"),
    MessagesPlaceholder("agent_scratchpad"),   # ← 历史步骤转成的消息
    ("human", "{input}"),
])
# agent_scratchpad = 把所有 AgentStep.messages 拼起来
# 即：[AIMessage(tc), ToolMessage, AIMessage(tc), ToolMessage, ...]
# 这就是 LLM 看到的"我之前想了什么、做了什么、得到了什么"

# pip install langchain
from langchain_core.agents import AgentAction, AgentFinish, AgentStep

# ============ ① AgentAction：要执行工具 ============
action = AgentAction(
    tool="search_weather",
    tool_input={"city": "北京"},
    log="Thought: 我需要查北京天气\nAction: search_weather",
)
print("Action:", action.tool, action.tool_input)

# .messages 把 action 转成 AIMessage
print("等价消息:", action.messages)
# → [AIMessage(content='...', additional_kwargs={'tool_calls': [...]})]

# ============ ② AgentStep：一步的完整记录 ============
step = AgentStep(action=action, observation='{"temp": 25}')
print("\nStep:", step.action.tool, "→", step.observation)
# .messages 把 step 转成 [AIMessage(tool_calls), ToolMessage]
print("等价消息:", [type(m).__name__ for m in step.messages])
# → ['AIMessage', 'ToolMessage']

# ============ ③ AgentFinish：循环结束 ============
finish = AgentFinish(
    return_values={"output": "北京今天 25 度，晴天。"},
    log="Thought: 信息齐全\nFinal Answer: 北京今天25度晴天",
)
print("\nFinish:", finish.return_values["output"])
# 这就是循环的终点，return_values 给用户

# ============ ④ 模拟一个完整循环的判断逻辑 ============
def decide(ai_message_tool_calls):
    """模拟 AgentExecutor 的核心判断。"""
    if ai_message_tool_calls:        # 有 tool_calls → Action
        tc = ai_message_tool_calls[0]
        return AgentAction(tool=tc["name"], tool_input=tc["args"], log="")
    else:                            # 无 tool_calls → Finish
        return AgentFinish(return_values={"output": "完成"}, log="")

print("\n判断1:", type(decide([{"name":"search","args":{}}])).__name__)  # AgentAction
print("判断2:", type(decide([])).__name__)                                # AgentFinish