🎯 Agent 实战 ★

def create_tool_calling_agent(
    llm: BaseLanguageModel,
    tools: Sequence[BaseTool],
    prompt: ChatPromptTemplate,
    *,
    message_formatter: MessageFormatter = format_to_tool_messages,
) -> Runnable:
    """创建一个使用工具的 agent。

    Args:
        llm: 作为 agent 大脑的 LLM
        tools: agent 可用的工具
        prompt: 提示模板 —— 【必须】包含 agent_scratchpad 变量
    Returns:
        一个 Runnable：输入 prompt 变量+历史，输出 AgentAction 或 AgentFinish
    """
    # 校验 prompt 必须有 agent_scratchpad（LC7 讲过为什么）
    missing_vars = {"agent_scratchpad"}.difference(prompt.input_variables)
    if missing_vars:
        raise ValueError(f"Prompt 缺少必需变量: {missing_vars}")

    # 必须支持 bind_tools（LC3 学过）
    if not hasattr(llm, "bind_tools"):
        raise ValueError("LLM 必须实现 bind_tools()")

    # 内部组装：本质是一条 LCEL 管道（LC5）
    # prompt（含 scratchpad）| bind_tools(model) | 解析出 Action/Finish
    llm_with_tools = llm.bind_tools(tools)
    agent = (
        {
            # 把 intermediate_steps（历史步骤）转成消息，塞进 scratchpad
            "agent_scratchpad": lambda x: format_to_tool_messages(x["intermediate_steps"]),
            "input": lambda x: x["input"],
            "chat_history": lambda x: x.get("chat_history", []),
        }
        | prompt
        | llm_with_tools
        | ToolCallingAgentOutputParser()  # 解析 AIMessage → AgentAction/Finish
    )
    return agent

class AgentExecutor(Chain):
    agent: Runnable          # create_tool_calling_agent 的返回值
    tools: Sequence[BaseTool]
    max_iterations: int = 15  # 步数上限（防死循环，对应 F3 章）

    def _call(self, inputs):
        intermediate_steps = []   # AgentStep 历史列表（LC7）

        for iteration in range(self.max_iterations):  # F3 的"步数上限"停止条件
            # ① Plan：调 agent（单步大脑），拿到 Action 或 Finish
            output = self.agent.invoke({
                **inputs,
                "intermediate_steps": intermediate_steps,
            })

            if isinstance(output, AgentFinish):       # ② Finish → 循环结束
                return output.return_values           # F3 的"自然完成"停止条件

            # ③ Action → 执行工具
            action = output  # AgentAction
            tool = find_tool(self.tools, action.tool)
            observation = tool.invoke(action.tool_input)

            # ④ Update：记录这一步，进入下一轮
            intermediate_steps.append(AgentStep(action=action, observation=observation))

        return {"output": "达到最大步数限制"}

# pip install langchain langchain-openai
# export OPENAI_API_KEY="sk-..."
from langchain_classic.agents import (
    create_tool_calling_agent, AgentExecutor, tool,
)
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# ============ ① 定义工具（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)

tools = [add, multiply, get_word_length]

# ============ ② 定义 prompt（LC2 + LC7 的 scratchpad）============
# 注意必须包含 agent_scratchpad 占位符！
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个数学和文字助手。你可以使用工具。"),
    ("placeholder", "{chat_history}"),       # 可选：对话历史
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),   # 必须！历史步骤注入这里
])

# ============ ③ 创建 agent（单步大脑）+ executor（循环发动机）============
model = ChatOpenAI(model="gpt-4o-mini")
agent = create_tool_calling_agent(model, tools, prompt)
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,                      # 打印每一步的思考过程！
    max_iterations=10,                 # 步数上限
    return_intermediate_steps=True,    # 返回中间步骤（调试用）
)

# ============ ④ 运行！观察完整的循环轨迹 ============
result = agent_executor.invoke({
    "input": "(3加5)乘以单词hello的长度，结果是多少？"
})

print("\n===== 最终结果 =====")
print("答案:", result["output"])

print("\n===== 中间步骤（Agent 的思考轨迹）=====")
for i, step in enumerate(result["intermediate_steps"], 1):
    action = step.action
    print(f"第{i}步: 调用 {action.tool}({action.tool_input}) → {step.observation}")

# 典型输出（verbose 会打印详细过程）：
# > Entering new AgentExecutor chain...
# 第1步: 调用 add({'a': 3, 'b': 5}) → 8
# 第2步: 调用 get_word_length({'word': 'hello'}) → 5
# 第3步: 调用 multiply({'a': 8, 'b': 5}) → 40
# 答案: 结果是 40
# > Finished chain.