面向新手完整教程复制即可运行包含知识点讲解、完整代码、依赖安装、官方文档地址、每一步拆解。 环境要求Python 3.9‑3.11 推荐LangChain 新版 API使用阿里云通义千问兼容 OpenAI 接口。一、整体知识点总览本篇你会学到LangChain Agent 是什么Agent 大模型 工具 思考决策大模型自己判断什么时候调用工具、调用哪个工具ReAct 思考‑行动‑观察模式tool装饰器如何自定义 LangChain 工具定义工具名字、入参、描述大模型靠描述知道工具能干什么兼容 OpenAI 格式调用第三方大模型阿里云百炼通义 qwen‑pluscreate_agent快速创建 Agent系统提示词约束 Agent 行为Agent 调用invoke()执行对话读取返回结果ReAct 核心逻辑思考 → 选择工具 → 执行工具拿到结果 → 交给大模型整理回答Agent 核心思想大模型不是直接回答遇到自己不能回答的内容主动选择工具调用拿到外部数据再整理输出。示例中时间、天气不属于大模型内部知识交给自定义工具获取。二、前置准备1. 安装依赖库打开终端执行pip install langchain langchain-core langchain-openailangchainAgent 核心库langchain‑core基础抽象、tool、消息对象langchain‑openai封装 ChatOpenAI兼容 OpenAI 接口不仅可以调用 OpenAI也能调用阿里云、DeepSeek 等兼容接口2. 获取阿里云百炼 API‑KEY登录阿里云百炼平台https://www.aliyun.com/product/bailian创建 API‑KEY拿到DASHSCOPE_API_KEY设置环境变量Windows cmdset DASHSCOPE_API_KEY你的keyMac/Linuxexport DASHSCOPE_API_KEY你的key⚠️不要把 key 硬编码写在代码里使用环境变量os.getenv()读取。3. 官方文档地址去哪里查文档LangChain 官方 Agent 文档https://python.langchain.com/docs/modules/agents/create_agent 快速代理https://python.langchain.com/docs/how_to/agent_create_agent/tool 自定义工具https://python.langchain.com/docs/how_to/custom_tools/阿里云百炼 OpenAI 兼容模式文档https://help.aliyun.com/zh/bailian/developer-reference/compatible-with-openai-api三、完整可直接复制全部代码新建文件agent_demo.py把下面全部复制进去。import os from datetime import datetime from langchain.agents import create_agent from langchain_core.tools import tool from langchain_openai import ChatOpenAI # 1.初始化大模型对象 llm ChatOpenAI( modelqwen-plus, temperature0.75, api_keyos.getenv(DASHSCOPE_API_KEY), base_urlhttps://ws-239p9rdg91gdeh5d.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 ) # 2.定义自定义工具 tool 装饰器 tool( description获取指定城市的当前时间,当用户询问时间、现在几点、当前时间等问题时调用此工具。 参数: city,字符串类型,城市,比如:北京,上海 返回值:当前城市的时间字符串 ) def get_current_time(city: str) - str: 获取城市当前时间 now_str datetime.now().strftime(%Y年%m月%d日 %H:%M:%S) return f{city}的当前时间是{now_str} tool( description获取指定城市的当前天气, 当用户询问天气,气温等问题时,调用此工具 参数: city,字符串类型,城市,比如:北京,上海 返回值:当前城市的天气数据字符串 ) def get_current_weather(city: str) - str: 获取城市天气 weather_data { 北京: 晴天温度 28°C湿度 45%空气质量良, 上海: 多云温度 30°C湿度 70%空气质量优, 广州: 阵雨温度 32°C湿度 85%空气质量良, 深圳: 晴天温度 31°C湿度 65%空气质量优, 杭州: 阴天温度 27°C湿度 60%空气质量良, } weather_res weather_data.get(city, f未找到{city}的天气数据请尝试查询: 北京、上海、广州、深圳、杭州) return f{city}的当前天气是{weather_res} # 工具列表Agent只能使用放到这个列表的工具 tools [get_current_time, get_current_weather] # 3.系统提示词约束Agent行为逻辑 system_prompt 你是一个智能助手 你可以使用工具来解决问题 工具列表: 1:当用户询问时间、现在几点、当前时间等问题时,调用get_current_time工具 2:当用户询问天气,气温等问题时,调用get_current_weather工具 请根据用户的问题,自主决定是否调用工具,调用哪个工具,调用顺序 如果不需要工具,直接回答用户的问题 # 创建Agent agent create_agent( modelllm, toolstools, system_promptsystem_prompt, debugTrue # debugTrue打印中间思考、工具调用日志新手强烈建议打开 ) # 4.调用Agent执行对话 invoke result agent.invoke( {messages: [{role: user, content: 北京的天气是什么}]} ) # 打印完整返回对象 print(完整返回结果) print(result) # 取出最后一条AI回复内容 print(\n最终AI回答) print(result.get(messages)[-1].content)运行命令python agent_demo.py四、逐块知识点讲解①导入模块import os from datetime import datetime from langchain.agents import create_agent from langchain_core.tools import tool from langchain_openai import ChatOpenAIos读取环境变量保护密钥不硬编码密钥datetime获取系统当前时间给工具使用create_agentLangChain 新版快速创建 Agent封装好 ReAct 逻辑不用手写复杂提示词tool装饰器把普通 Python 函数包装成 LangChain 可识别的工具对象大模型完全依靠 description 知道工具功能、参数描述写的差 Agent 就不会调用工具。ChatOpenAI标准 OpenAI 对话模型类base_url修改即可对接阿里云、DeepSeek、OpenAI 等兼容接口。②初始化大模型 llm 对象llm ChatOpenAI( modelqwen-plus, temperature0.75, api_keyos.getenv(DASHSCOPE_API_KEY), base_urlxxx )model模型名称阿里云百炼上面模型标识temperature0‑1越低回答越确定越高越有创造性Agent 场景一般 0‑0.8api_keyos.getenv(DASHSCOPE_API_KEY)从系统环境变量读取密钥禁止直接写字符串密钥到代码上传代码会泄露密钥base_url兼容 OpenAI 的接口地址换成 OpenAI 官方就填https://api.openai.com/v1关键点不是只能调用 OpenAI只要接口兼容 OpenAI 格式都能用 ChatOpenAI。③tool 自定义工具Agent 最重要知识点tool( description获取指定城市的当前时间,当用户询问时间、现在几点、当前时间等问题时调用此工具。 参数: city,字符串类型,城市,比如:北京,上海 返回值:当前城市的时间字符串 ) def get_current_time(city: str) - str: now_str datetime.now().strftime(%Y年%m月%d日 %H:%M:%S) return f{city}的当前时间是{now_str}tool装饰器把普通 Python 函数转为 LangChainTool对象Agent 才能识别description至关重要大模型看不到你的函数代码只能看描述文本描述要写清楚什么时候调用、参数是什么、返回什么。描述写模糊 Agent 就不会触发工具调用。函数参数必须写类型注解city:strAgent 需要知道参数类型返回值也要标注。工具函数写普通业务逻辑return 返回字符串结果Agent 拿到 return 的字符串再交给大模型整理。工具就是一段 Python 代码Agent 决定调用 → 传入参数执行函数 → 获取返回文本 → 把文本塞回大模型上下文。把所有工具放入列表tools [get_current_time, get_current_weather]Agent只能使用列表里面注册过的工具写了装饰器不放进列表Agent 看不见。④system_prompt 系统提示词system_prompt 你是一个智能助手 你可以使用工具来解决问题 工具列表: 1:当用户询问时间、现在几点、当前时间等问题时,调用get_current_time工具 2:当用户询问天气,气温等问题时,调用get_current_weather工具 请根据用户的问题,自主决定是否调用工具,调用哪个工具,调用顺序 如果不需要工具,直接回答用户的问题 系统提示词给大模型设定角色与规则辅助 Agent 判断什么时候触发工具。create_agent内部会自动拼接工具元信息你也可以额外写业务约束。⑤创建 Agent 对象 create_agentagent create_agent( modelllm, toolstools, system_promptsystem_prompt, debugTrue )model大模型实例tools可用工具列表system_prompt系统提示词debugTrue打印完整中间过程日志思考、选择工具、入参、工具返回新手调试必须打开排查为什么不调用工具。create_agent是 LangChain 新版高层封装底层就是 ReAct Agent省去手动构建 ReAct prompt。⑥agent.invoke () 发起对话result agent.invoke( {messages: [{role: user, content: 北京的天气是什么}]} )invoke()传入消息列表格式和 OpenAI messages 完全一样。 执行流程 ReAct思考‑行动‑观察用户提问北京天气是什么大模型思考我需要调用get_current_weather参数 city北京Agent 执行工具函数拿到工具返回字符串将工具返回结果塞回对话上下文大模型整理工具结果输出自然语言回答读取结果print(result.get(messages)[-1].content)result[messages]保存完整对话全部消息用户消息、大模型思考、工具调用消息、工具返回、AI 最终回复最后一条消息就是最终 AI 输出。五、新手常见踩坑清单工具tool的description写的不清楚 → Agent 不调用工具。✅解决描述写清楚触发条件参数说明。写了 tool但是没有放到tools [...]列表 → Agent 看不到工具。API_KEY 硬编码写在代码提交 git 泄露密钥 → 使用os.getenv()。base_url 写错网络不通阿里云权限没开通模型调用 → 报错 401、404。关闭 debugTrue看不到中间日志不知道为什么没有调用工具 → 开发阶段打开 debug。工具函数返回不要返回对象 / 字典尽量返回字符串。Agent 工具输出建议返回 str。六、扩展练习自己动手改代码修改用户提问测试现在北京几点观察 Agent 是否调用 get_current_time。新增一个工具获取今天星期几仿照上面格式写一个新 tool 函数加入 tools 列表。修改 temperature对比 Agent 输出变化。七、文档链接汇总方便后续查阅create_agent 快速代理https://python.langchain.com/docs/how_to/agent_create_agent/自定义工具 toolhttps://python.langchain.com/docs/how_to/custom_tools/LangChain Agent 总文档https://python.langchain.com/docs/modules/agents/阿里云百炼 OpenAI 兼容接口文档https://help.aliyun.com/zh/bailian/developer-reference/compatible-with-openai-api