【LangChain】第一个Agent：10分钟上手LangChain新架构

【LangChain】第一个Agent：10分钟上手LangChain新架构

系列文章第2篇 | 目标：从零开始，用10行代码跑通你的第一个AI Agent

一、核心概念：搞清楚我们在做什么

想象一下，你刚搬进一个新公寓。LangChain就像是这个公寓的物业管理处——它提供基础设施（水电网络）、制定规则（装修规范）、还能帮你对接各种服务商（搬家公司、保洁阿姨）。

而你要搭建的Agent（智能体），就像是雇佣了一个全能管家：

• 你问"今天会下雨吗？"，管家会思考：需要查天气 → 行动：打开天气APP → 观察：看到预报 → 回答："记得带伞！"

这个"思考→行动→观察→再思考"的循环，就是著名的 ReAct（Reasoning + Acting）框架。

为什么要用新的 create_agent API？

LangChain的新架构就像从"手动挡"升级到了"自动挡"：

• 旧方式：initialize_agent() + AgentExecutor，配置繁琐，容易出错
• 新方式：create_agent()，一行代码搞定，自动处理消息状态、工具调用、流式输出

---

二、快速上手：10行代码创建你的第一个Agent

步骤1：环境准备（3分钟）

# 创建项目目录
mkdir my-first-agent
cd my-first-agent

# 创建虚拟环境（强烈推荐！）
python -m venv .venv

# 激活虚拟环境
# Mac/Linux:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

# 安装核心依赖
pip install -U langchain langchain-openai langgraph python-dotenv

为什么需要这些包？

• langchain：核心框架，像公寓的基础设施
• langchain-openai：对接OpenAI模型的"门禁卡"
• langgraph：新架构的底层引擎，负责管理Agent的执行流程
• python-dotenv：管理API密钥的安全"保险箱"

步骤2：API密钥管理（安全第一！）

创建 .env 文件：

# .env 文件 - 这个文件永远不要提交到Git！
OPENAI_API_KEY=sk-your-key-here

然后创建 agent.py：

from dotenv import load_dotenv
load_dotenv()  # 自动加载.env文件，像打开保险箱取钥匙

生活小贴士：把 .env 加入 .gitignore，就像把家门钥匙藏在地毯下——虽然方便，但别让外人知道！

步骤3：10行代码，见证奇迹

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

# 定义一个"工具"——让Agent能查天气
def get_weather(city: str) -> str:
    """获取指定城市的天气信息"""
    return f"{city}今天阳光明媚，25°C，适合出门！"

# 创建Agent（核心就这3行！）
agent = create_agent(
    model="gpt-4o-mini",  # 模型名称 国内的话可以使用阿里的模型，比如阿里的qwen-plus，同时需要设置baseUrl
    tools=[get_weather],  # 给Agent配备的工具箱
    system_prompt="你是一个 helpful 的助手，可以回答天气问题"  # 人设
)

# 运行Agent
result = agent.invoke({
    "messages": [{"role": "user", "content": "北京天气怎么样？"}]
})
print(result["messages"][-1].content)

输出示例：

我来帮您查询北京的天气情况。

【思考】用户询问北京天气，我需要使用天气工具获取信息。

【行动】调用 get_weather 工具，输入："北京"

【观察】工具返回：北京今天阳光明媚，25°C，适合出门！

北京今天天气不错，阳光明媚，气温25°C，是个适合出门的好日子！

---

三、深度解析：这10行代码到底做了什么？

1. create_agent 的幕后故事

当你调用 create_agent() 时，LangChain在后台做了一堆"脏活累活"：

你的调用
    ↓
LangChain自动：
  1. 初始化 LangGraph 状态图
  2. 配置 ReAct 循环逻辑
  3. 绑定工具到模型（bind_tools）
  4. 设置消息状态管理器
  5. 配置系统提示词模板
    ↓
返回一个可直接运行的 Agent 对象

对比旧版，以前你需要手动写：

# 旧版（繁琐且容易出错）
from langchain.agents import create_react_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant"),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])
agent = create_react_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# ... 还要手动处理消息格式

2. ReAct循环的解剖图

让我们用做番茄炒蛋来类比ReAct循环：

ReAct步骤	番茄炒蛋类比	Agent实际行为
思考(Thought)	"我需要番茄和鸡蛋"	分析用户意图，决定是否需要工具
行动(Action)	打开冰箱拿食材	调用 get_weather 等工具
观察(Observation)	"番茄是红的，鸡蛋是圆的"	接收工具返回的结果
再思考	"现在可以炒了"	判断信息是否足够回答问题
最终回答	"番茄炒蛋做好了！"	生成自然语言回复

卡通风格的厨房场景，一个机器人厨师正在做番茄炒蛋，旁边有标注箭头指向"思考-行动-观察"的流程

3. 流式输出：让Agent"边想边说"

如果你想看Agent的"内心戏"，可以用流式模式：

# 流式输出，像看直播一样看Agent思考
for chunk in agent.stream(
    {"messages": [{"role": "user", "content": "上海天气如何？"}]},
    stream_mode="values"  # 实时返回状态更新
):
    msg = chunk["messages"][-1]
    if msg.content:
        print(f"🤖 {type(msg).__name__}: {msg.content[:100]}...")
    
    # 如果看到工具调用，特别标注
    if hasattr(msg, 'tool_calls') and msg.tool_calls:
        tool_names = [tc['name'] for tc in msg.tool_calls]
        print(f"🔧 正在调用工具: {tool_names}")

输出效果：

🤖 HumanMessage: 上海天气如何？
🤖 AIMessage: 【思考】用户询问上海天气...
🔧 正在调用工具: ['get_weather']
🤖 ToolMessage: 上海今天阳光明媚...
🤖 AIMessage: 上海今天天气很好，阳光明媚...

---

四、实战案例：给Agent配备"瑞士军刀"

案例：多工具智能助手

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
import random

@tool
def calculate(expression: str) -> str:
    """计算数学表达式，如 '2 + 2' 或 '10 * 5'"""
    try:
        result = eval(expression)  # 生产环境请用更安全的方式！
        return f"计算结果：{result}"
    except:
        return "计算出错，请检查表达式格式"

@tool
def get_fortune(sign: str) -> str:
    """获取星座运势，支持：白羊、金牛、双子等12星座"""
    fortunes = ["大吉", "中吉", "小吉", "平平", "需要注意"]
    return f"{sign}座今日运势：{random.choice(fortunes)}，宜写代码，忌不测试就上线"

@tool
def search_docs(query: str) -> str:
    """搜索内部技术文档"""
    docs = {
        "LangChain": "LangChain是一个用于构建LLM应用的框架",
        "ReAct": "ReAct是Reasoning + Acting的缩写，一种Agent架构",
        "API Key": "请妥善保管API Key，不要硬编码在代码中"
    }
    for key, value in docs.items():
        if query.lower() in key.lower():
            return f"找到文档：{value}"
    return "未找到相关文档"

# 创建多工具Agent
multi_tool_agent = create_agent(
    model="gpt-4o",
    tools=[calculate, get_fortune, search_docs],
    system_prompt="""你是一个全能助手，可以：
1. 进行数学计算
2. 查询星座运势（仅当用户明确提到星座时）
3. 搜索技术文档
请根据用户需求选择合适的工具。"""
)

# 测试不同场景
test_queries = [
    "3.14乘以2的平方是多少？",
    "双子座今天运势怎么样？",
    "什么是ReAct框架？"
]

for query in test_queries:
    print(f"\n{'='*50}")
    print(f"📝 用户：{query}")
    result = multi_tool_agent.invoke({
        "messages": [{"role": "user", "content": query}]
    })
    print(f"✅ 助手：{result['messages'][-1].content}")

---

五、最佳实践：避开新手村的"坑"

✅ 必须做的（Dos）

1. 工具描述要详细

   # ❌ 不好的描述
   def search(query: str): "搜索功能"
   
   # ✅ 好的描述 - 告诉Agent什么时候用
   def search(query: str): 
       """当需要获取实时信息、新闻或当前事件时使用此工具。
       输入应该是具体的搜索关键词。
       例如：'2024年Python最新版本'"""
   

2. 始终使用虚拟环境

   # 避免依赖地狱，就像不要把所有调料倒进一个锅里
   python -m venv .venv
   

3. 设置迭代限制，防止Agent"钻牛角尖"

   # 在配置中设置（后续文章会详细讲）
   # max_iterations=5  # 最多思考5轮
   

❌ 避免做的（Don'ts）

1. 不要把API Key硬编码

   # ❌ 危险！
   api_key = "sk-1234567890abcdef"
   
   # ✅ 安全
   import os
   api_key = os.getenv("OPENAI_API_KEY")
   

2. 不要给Agent太多工具（选择困难症）

   就像你去餐厅，菜单有200道菜反而不知道怎么选。建议一个Agent专注3-5个核心工具。

3. 不要忽视错误处理

   @tool
   def risky_operation(data: str) -> str:
       try:
           # 你的逻辑
           return result
       except Exception as e:
           return f"操作失败：{str(e)}。请检查输入参数。"
   

---

六、延伸阅读与下一步

恭喜！你已经成功创建了第一个Agent。但这只是冰山一角：

接下来可以探索：

• 第3篇：模型集成详解——如何让Agent"换脑"（GPT-4、Claude、Gemini切换自如）
• 第4篇：Tools工具系统深度解析——打造专业的工具箱
• 第6篇：Agent记忆系统——让Agent记住你们的对话

官方资源：

• LangChain官方Quickstart
• LangGraph文档
• ReAct论文原理解析

课后作业：

试着修改上面的天气工具，让它真的调用一个天气API（如OpenWeatherMap），而不是返回固定字符串。提示：你需要 requests 库和API Key。

---

💡 小彩蛋：如果你看到Agent在思考时"胡言乱语"，不要慌——就像教小朋友做题，多给几个例子（Few-shot Prompting），它很快就会开窍。我们会在第5篇详细讲解Prompt工程化技巧！

---

系列文章导航：

• 上一篇：LangChain新架构概览
• 下一篇：模型集成详解（敬请期待）

关注公众号【dev派】，发送 "agent" 获取全部源码和模板