🏗️ 预构建 Agent ★

def create_react_agent(
    model,                      # LLM（静态实例 或 动态选择函数）
    tools,                      # 工具列表 或 ToolNode
    *,
    prompt=None,                # 系统提示（字符串 / 模板 / 函数）
    response_format=None,       # 结构化输出 schema
    pre_model_hook=None,        # 模型调用前的钩子（如消息裁剪）
    post_model_hook=None,       # 模型调用后的钩子
    state_schema=None,          # 自定义状态 schema
    checkpointer=None,          # 检查点（记忆/中断，LG6）
    interrupt_before=None,      # 在某节点前中断（HITL，LG6）
    interrupt_after=None,
    debug=False,
) -> CompiledStateGraph:
    """创建一个循环调用工具直到停止的 agent 图。

    返回 CompiledStateGraph（继承 Pregel，LG5）。
    内部构建：agent（调LLM）↔ tools（ToolNode）循环，
    用 tools_condition 条件边路由（LG3）。

    ⚠️ 已废弃，建议迁移到 langchain.agents.create_agent（middleware 系统）。
       但仍是学习 ReAct 模式的最佳参考。
    """

# 内部状态：就是 MessagesState（LG2 的 add_messages reducer！）
class AgentState(TypedDict):
    messages: Annotated[Sequence[BaseMessage], add_messages]   # ← LG2
    remaining_steps: NotRequired[RemainingSteps]               # 步数限制

# create_react_agent 内部等价于构建这个图（LG1 + LG3）：
def _build_graph(model, tools):
    graph = StateGraph(AgentState)

    # 节点1：agent（调 LLM，绑定工具 LC3+LC6）
    def call_model(state):
        response = model.bind_tools(tools).invoke(state["messages"])
        return {"messages": [response]}
    graph.add_node("agent", call_model)

    # 节点2：tools（执行工具，用 ToolNode）
    graph.add_node("tools", ToolNode(tools))

    # 边：START → agent
    graph.add_edge(START, "agent")

    # 条件边（LG3）：agent 后由 tools_condition 路由
    graph.add_conditional_edges("agent", tools_condition)   # ← LG3 的核心！

    # tools 执行完回到 agent，形成循环（F3 的 Agent 循环！）
    graph.add_edge("tools", "agent")

    return graph.compile(checkpointer=checkpointer)

class ToolNode(RunnableCallable):
    """处理工具执行的节点。
    从状态读 AIMessage 的 tool_calls，并行执行对应工具，
    把结果作为 ToolMessage 返回。支持错误处理。"""

def tools_condition(state, messages_key="messages") -> Literal["tools", "__end__"]:
    """条件路由函数：实现 ReAct agent 的标准逻辑。
    如果最后一条 AIMessage 含 tool_calls → 路由到 "tools"；
    否则 → 路由到 "__end__"（结束）。

    这就是 F3 章的 Action/Finish 二态判断！（LC7）"""
    last_msg = state[messages_key][-1]
    if last_msg.tool_calls:
        return "tools"     # AgentAction → 去执行工具
    return "__end__"       # AgentFinish → 结束

# pip install langgraph langchain-openai
# export OPENAI_API_KEY="sk-..."
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool

# ① 定义工具（LC6 的 @tool）
@tool
def add(a: int, b: int) -> int:
    """计算两个数的和。"""
    return a + b

@tool
def multiply(a: int, b: int) -> int:
    """计算两个数的乘积。"""
    return a * b

@tool
def get_word_length(word: str) -> int:
    """返回单词的字符长度。"""
    return len(word)

# ② 一行构建完整 Agent！（对比 LC8 的 create_tool_calling_agent + AgentExecutor）
model = ChatOpenAI(model="gpt-4o-mini")
agent = create_react_agent(
    model=model,
    tools=[add, multiply, get_word_length],
    prompt="你是一个数学和文字助手，可以使用工具。",
)

# ③ 直接用！invoke / stream 都行
result = agent.invoke({
    "messages": [("human", "(3+5)乘以单词hello的长度是多少？")]
})
print("答案:", result["messages"][-1].content)
# → "结果是 40"

# 查看完整轨迹（LC7 的 messages step 都在 messages 列表里）
print("\n轨迹:")
for m in result["messages"]:
    tc = getattr(m, "tool_calls", [])
    print(f"  [{m.type}] {m.content[:40] if m.content else '(调工具)'}"
          + (f" → {tc}" if tc else ""))

from langgraph.checkpoint.memory import InMemorySaver

agent = create_react_agent(
    model=model,
    tools=[add, multiply],
    checkpointer=InMemorySaver(),   # ← 加记忆
)

config = {"configurable": {"thread_id": "chat-1"}}
agent.invoke({"messages": [("human", "我叫张三")]}, config)
result = agent.invoke({"messages": [("human", "我叫什么？")]}, config)
print(result["messages"][-1].content)  # → "你叫张三"

agent = create_react_agent(
    model=model,
    tools=[dangerous_tool],
    checkpointer=InMemorySaver(),
    interrupt_before=["tools"],   # ← 工具执行【前】暂停，等人确认！
)

config = {"configurable": {"thread_id": "t1"}}
# 第一次：执行到 tools 前暂停
agent.invoke({"messages": [("human", "删除文件")]}, config)

# 检查即将执行的工具，人工确认后继续
state = agent.get_state(config)
print("即将执行:", state.tasks)
agent.invoke(None, config)   # 传 None 继续执行（人工批准后）

def trim_messages(state):
    """调 LLM 前，只保留最近 20 条消息。"""
    return {"messages": state["messages"][-20:]}

agent = create_react_agent(
    model=model,
    tools=tools,
    pre_model_hook=trim_messages,   # ← 每次调 LLM 前自动裁剪
)