1. 为什么我建议你用 LangGraph 而不是裸写 while 循环如果你最近在折腾 AI Agent大概率已经看过不少“概念文”Function Calling、ReAct、多智能体协作……名词一堆但真到动手时还是不知道从哪下手。LangGraph 就是来解决这个问题的——它把 Agent 的执行流程抽象成一张有向图节点是“动作”边是“跳转条件”状态在节点之间流转。你不再需要手写一堆 if-else 和 while 循环去控制“什么时候调工具、什么时候结束”而是把逻辑画成图让框架去跑。这篇教程面向的是完全没接触过 LangGraph、但会一点 Python的读者。我会从 StateGraph、节点、边、Reducer 这几个核心概念讲起然后带你落地一个能真正跑起来的最小 Agent它能接收用户问题、判断是否需要调用工具、执行工具、把结果回传给模型、最后输出答案。整个过程用 TaoToken 统一 Key 接入模型你不需要在多个厂商之间来回切换配置。我试过用纯 Python 写 Agent 循环代码量不大但状态管理很容易乱尤其是加上“人工确认”“重试”“多轮工具调用”之后控制流会变得非常难读。LangGraph 的价值就在于把这些控制流显式化调试的时候你能清楚看到每一步走到了哪个节点。2. TaoToken 前置准备一个 Key 打通模型接入在写代码之前先把模型通道准备好。LangGraph 本身不绑定任何模型厂商它通过 LangChain 的 ChatModel 接口调用 LLM。所以你需要一个兼容 OpenAI 协议的 API 端点。TaoToken 提供的就是这样一个统一入口一个 Key、一个 Base URL就能调用多种模型省去你分别注册、分别管理额度的麻烦。你需要准备三样东西第一一个 TaoToken 账号登录后进入控制台创建 API Key。地址是https://taotoken.net/api-keys创建后复制那串sk-开头的 Key后面配置里要用。第二确认你要用的模型名称。TaoToken 的模型列表在文档里可以查到常见的有gpt-4o、claude-3-5-sonnet、deepseek-chat等。本文示例用gpt-4o你换成别的也行只要 LangChain 的 OpenAI 兼容接口能识别。第三记住 Base URLhttps://taotoken.net/api。注意这里不要加任何路径后缀LangChain 会自动拼接/v1/chat/completions。提示如果你之前用过 OpenAI 官方 SDK把base_url换成 TaoToken 的地址、api_key换成 TaoToken 的 Key 即可其他代码不用动。这就是统一 Key 的好处。3. 可复制配置config.toml 与 settings.json 骨架为了让配置和代码分离我习惯把模型参数放在独立文件里。下面给你两份可直接复制的骨架放在项目根目录即可。config.toml用来存模型和运行参数[model] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model_name gpt-4o temperature 0.0 max_tokens 2048 [agent] recursion_limit 10 max_tool_calls 5settings.json用来存 Agent 的运行时开关方便你后面做实验{ agent: { name: minimal-langgraph-agent, enable_tools: true, enable_interrupt: false, log_level: INFO }, tools: { calculator: true, search: false, read_file: false } }读取配置的代码很简单用 Python 标准库tomllib3.11或tomli即可。环境变量TAOTOKEN_API_KEY建议写在.env里用python-dotenv加载避免把 Key 硬编码进代码。import os import json import tomllib from dotenv import load_dotenv load_dotenv() with open(config.toml, rb) as f: config tomllib.load(f) with open(settings.json, r, encodingutf-8) as f: settings json.load(f) api_key os.environ[config[model][api_key_env]]这样你的 Key 只存在于环境变量中代码和配置文件都可以安全地提交到仓库。4. 从 StateGraph 到可运行 Agent完整代码拆解4.1 定义状态Agent 的“记忆”长什么样状态是 LangGraph 的核心。它贯穿整个执行过程每个节点都能读取和修改它。我们用TypedDict定义状态结构其中messages字段用add_messages作为 reducer保证新消息是追加而不是覆盖。from typing import TypedDict, Annotated from langgraph.graph.message import add_messages class AgentState(TypedDict): messages: Annotated[list, add_messages] step: int tool_results: listadd_messages这个 reducer 很关键。Agent 的对话历史需要不断累积如果每次节点返回都覆盖messages模型就看不到之前的上下文了。加上这个注解后LangGraph 会自动把新消息合并进列表。4.2 定义工具给 Agent 装上“手”工具就是普通 Python 函数加上tool装饰器。docstring 非常重要模型靠它判断什么时候该调用这个工具。from langchain_core.tools import tool tool def calculator(expression: str) - str: 计算数学表达式输入如 (15 * 23) (48 / 6) try: allowed set(0123456789-*/(). ) if not set(expression) allowed: return 表达式包含不允许的字符 return str(eval(expression)) except Exception as e: return f计算错误: {e} tool def read_file(filepath: str) - str: 读取本地文本文件内容输入文件路径 try: with open(filepath, r, encodingutf-8) as f: return f.read()[:2000] except Exception as e: return f读取失败: {e}注意calculator里我做了字符白名单校验直接eval用户输入在生产环境是危险的。这个细节很多教程会忽略但你真上线时必须处理。4.3 构建图节点、边与条件跳转现在把状态、工具、模型串起来。先初始化模型用 TaoToken 的 Base URLfrom langchain_openai import ChatOpenAI llm ChatOpenAI( modelconfig[model][model_name], base_urlconfig[model][base_url], api_keyapi_key, temperatureconfig[model][temperature], ) tools [calculator, read_file] llm_with_tools llm.bind_tools(tools)然后定义两个节点agent_node负责让模型思考并决定下一步tool_node负责执行模型请求的工具调用。from langgraph.graph import StateGraph, START, END def agent_node(state: AgentState) - AgentState: response llm_with_tools.invoke(state[messages]) return { messages: [response], step: state.get(step, 0) 1, } def tool_node(state: AgentState) - AgentState: last_message state[messages][-1] results [] tool_map {t.name: t for t in tools} for tool_call in last_message.tool_calls: func tool_map[tool_call[name]] output func.invoke(tool_call[args]) results.append({ tool_call_id: tool_call[id], role: tool, content: str(output), }) return {messages: results, tool_results: results} def should_continue(state: AgentState) - str: last_message state[messages][-1] if hasattr(last_message, tool_calls) and last_message.tool_calls: return tools return END最后组装图并编译graph StateGraph(AgentState) graph.add_node(agent, agent_node) graph.add_node(tools, tool_node) graph.add_edge(START, agent) graph.add_conditional_edges(agent, should_continue, {tools: tools, END: END}) graph.add_edge(tools, agent) app graph.compile()执行流程是START → agent → 判断 → tools → agent → 判断 → END。这就是标准的 ReAct 循环模型先推理需要工具就调用拿到结果再推理直到不需要工具就输出最终答案。5. 启动验证跑通第一个请求代码写完了跑一下看看。用HumanMessage构造输入调用app.invokefrom langchain_core.messages import HumanMessage result app.invoke( { messages: [HumanMessage(content帮我算一下 (15 * 23) (48 / 6) 等于多少)], step: 0, tool_results: [], }, {recursion_limit: config[agent][recursion_limit]}, ) print(result[messages][-1].content)如果一切正常你会看到类似输出(15 × 23) (48 ÷ 6) 345 8 353模型先识别出需要调用calculator工具返回353模型再组织成自然语言回答。整个过程你可以在日志里看到两次agent节点执行和一次tools节点执行。如果你想验证模型通道是否正常可以先用 TaoToken 的模型对话页面发一条测试消息确认 Key 和模型名没问题再跑代码。地址是https://taotoken.net/chat。6. 常见报错排查我踩过的几个坑报错一AuthenticationError: Incorrect API key provided先检查.env里的TAOTOKEN_API_KEY是否加载成功。可以在代码里打印api_key[:8]确认。另外确认base_url写的是https://taotoken.net/api不要多加/v1LangChain 会自己拼。报错二model not found模型名要和 TaoToken 文档里的一致。比如你写gpt-4但实际可用的是gpt-4o就会报这个错。建议先在模型对话页面确认模型可用再填进config.toml。报错三GraphRecursionError: Recursion limit of 10 reached说明 Agent 陷入了循环通常是工具一直返回错误、模型反复重试。解决办法有两个一是把recursion_limit调大二是检查工具函数的返回值是否合理。我建议在tool_node里加日志打印每次工具调用的输入输出很快就能定位。报错四tool_calls为空但模型不输出最终答案这种情况通常是模型返回了空内容。检查temperature是否设得太高或者max_tokens太小导致输出被截断。把temperature设为 0、max_tokens调到 2048 以上通常能解决。报错五工具执行结果格式不对tool_node返回的消息必须包含tool_call_id、role: tool和content三个字段。少任何一个下一轮agent_node调用模型时都会报格式错误。这个坑我在第一次写的时候踩过排查了半天。如果你在接入过程中遇到 Key 或通道相关的问题可以直接去 TaoToken 的接入文档对照检查https://taotoken.net/doc。文档里有各语言的完整示例包括 LangChain 的配置片段。7. 下一步从最小 Agent 到可用系统跑通这个最小示例后你可以沿着几个方向继续扩展。一是加更多工具比如数据库查询、HTTP 请求、文件写入让 Agent 能处理更复杂的任务。二是引入MemorySaver做检查点实现多轮对话和中断恢复这在需要人工确认的场景很有用。三是把app用 FastAPI 包一层暴露成 HTTP 接口方便前端或其他服务调用。如果你打算长期做编码类 Agent比如自动改代码、跑测试、提交 PR可以了解一下 TaoToken 的 Coding Plan它针对长上下文和频繁调用做了优化地址是https://taotoken.net/coding-plan。对于需要反复调试 Agent 流程的场景稳定的模型通道能省不少事。代码写到这里你已经有了一个能跑的最小闭环。接下来就是不断加工具、加节点、加条件边让它越来越接近你真正想要的那个 Agent。
1. 为什么我建议你用 LangGraph 而不是裸写 while 循环如果你最近在折腾 AI Agent大概率已经看过不少“概念文”Function Calling、ReAct、多智能体协作……名词一堆但真到动手时还是不知道从哪下手。LangGraph 就是来解决这个问题的——它把 Agent 的执行流程抽象成一张有向图节点是“动作”边是“跳转条件”状态在节点之间流转。你不再需要手写一堆 if-else 和 while 循环去控制“什么时候调工具、什么时候结束”而是把逻辑画成图让框架去跑。这篇教程面向的是完全没接触过 LangGraph、但会一点 Python的读者。我会从 StateGraph、节点、边、Reducer 这几个核心概念讲起然后带你落地一个能真正跑起来的最小 Agent它能接收用户问题、判断是否需要调用工具、执行工具、把结果回传给模型、最后输出答案。整个过程用 TaoToken 统一 Key 接入模型你不需要在多个厂商之间来回切换配置。我试过用纯 Python 写 Agent 循环代码量不大但状态管理很容易乱尤其是加上“人工确认”“重试”“多轮工具调用”之后控制流会变得非常难读。LangGraph 的价值就在于把这些控制流显式化调试的时候你能清楚看到每一步走到了哪个节点。2. TaoToken 前置准备一个 Key 打通模型接入在写代码之前先把模型通道准备好。LangGraph 本身不绑定任何模型厂商它通过 LangChain 的 ChatModel 接口调用 LLM。所以你需要一个兼容 OpenAI 协议的 API 端点。TaoToken 提供的就是这样一个统一入口一个 Key、一个 Base URL就能调用多种模型省去你分别注册、分别管理额度的麻烦。你需要准备三样东西第一一个 TaoToken 账号登录后进入控制台创建 API Key。地址是https://taotoken.net/api-keys创建后复制那串sk-开头的 Key后面配置里要用。第二确认你要用的模型名称。TaoToken 的模型列表在文档里可以查到常见的有gpt-4o、claude-3-5-sonnet、deepseek-chat等。本文示例用gpt-4o你换成别的也行只要 LangChain 的 OpenAI 兼容接口能识别。第三记住 Base URLhttps://taotoken.net/api。注意这里不要加任何路径后缀LangChain 会自动拼接/v1/chat/completions。提示如果你之前用过 OpenAI 官方 SDK把base_url换成 TaoToken 的地址、api_key换成 TaoToken 的 Key 即可其他代码不用动。这就是统一 Key 的好处。3. 可复制配置config.toml 与 settings.json 骨架为了让配置和代码分离我习惯把模型参数放在独立文件里。下面给你两份可直接复制的骨架放在项目根目录即可。config.toml用来存模型和运行参数[model] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model_name gpt-4o temperature 0.0 max_tokens 2048 [agent] recursion_limit 10 max_tool_calls 5settings.json用来存 Agent 的运行时开关方便你后面做实验{ agent: { name: minimal-langgraph-agent, enable_tools: true, enable_interrupt: false, log_level: INFO }, tools: { calculator: true, search: false, read_file: false } }读取配置的代码很简单用 Python 标准库tomllib3.11或tomli即可。环境变量TAOTOKEN_API_KEY建议写在.env里用python-dotenv加载避免把 Key 硬编码进代码。import os import json import tomllib from dotenv import load_dotenv load_dotenv() with open(config.toml, rb) as f: config tomllib.load(f) with open(settings.json, r, encodingutf-8) as f: settings json.load(f) api_key os.environ[config[model][api_key_env]]这样你的 Key 只存在于环境变量中代码和配置文件都可以安全地提交到仓库。4. 从 StateGraph 到可运行 Agent完整代码拆解4.1 定义状态Agent 的“记忆”长什么样状态是 LangGraph 的核心。它贯穿整个执行过程每个节点都能读取和修改它。我们用TypedDict定义状态结构其中messages字段用add_messages作为 reducer保证新消息是追加而不是覆盖。from typing import TypedDict, Annotated from langgraph.graph.message import add_messages class AgentState(TypedDict): messages: Annotated[list, add_messages] step: int tool_results: listadd_messages这个 reducer 很关键。Agent 的对话历史需要不断累积如果每次节点返回都覆盖messages模型就看不到之前的上下文了。加上这个注解后LangGraph 会自动把新消息合并进列表。4.2 定义工具给 Agent 装上“手”工具就是普通 Python 函数加上tool装饰器。docstring 非常重要模型靠它判断什么时候该调用这个工具。from langchain_core.tools import tool tool def calculator(expression: str) - str: 计算数学表达式输入如 (15 * 23) (48 / 6) try: allowed set(0123456789-*/(). ) if not set(expression) allowed: return 表达式包含不允许的字符 return str(eval(expression)) except Exception as e: return f计算错误: {e} tool def read_file(filepath: str) - str: 读取本地文本文件内容输入文件路径 try: with open(filepath, r, encodingutf-8) as f: return f.read()[:2000] except Exception as e: return f读取失败: {e}注意calculator里我做了字符白名单校验直接eval用户输入在生产环境是危险的。这个细节很多教程会忽略但你真上线时必须处理。4.3 构建图节点、边与条件跳转现在把状态、工具、模型串起来。先初始化模型用 TaoToken 的 Base URLfrom langchain_openai import ChatOpenAI llm ChatOpenAI( modelconfig[model][model_name], base_urlconfig[model][base_url], api_keyapi_key, temperatureconfig[model][temperature], ) tools [calculator, read_file] llm_with_tools llm.bind_tools(tools)然后定义两个节点agent_node负责让模型思考并决定下一步tool_node负责执行模型请求的工具调用。from langgraph.graph import StateGraph, START, END def agent_node(state: AgentState) - AgentState: response llm_with_tools.invoke(state[messages]) return { messages: [response], step: state.get(step, 0) 1, } def tool_node(state: AgentState) - AgentState: last_message state[messages][-1] results [] tool_map {t.name: t for t in tools} for tool_call in last_message.tool_calls: func tool_map[tool_call[name]] output func.invoke(tool_call[args]) results.append({ tool_call_id: tool_call[id], role: tool, content: str(output), }) return {messages: results, tool_results: results} def should_continue(state: AgentState) - str: last_message state[messages][-1] if hasattr(last_message, tool_calls) and last_message.tool_calls: return tools return END最后组装图并编译graph StateGraph(AgentState) graph.add_node(agent, agent_node) graph.add_node(tools, tool_node) graph.add_edge(START, agent) graph.add_conditional_edges(agent, should_continue, {tools: tools, END: END}) graph.add_edge(tools, agent) app graph.compile()执行流程是START → agent → 判断 → tools → agent → 判断 → END。这就是标准的 ReAct 循环模型先推理需要工具就调用拿到结果再推理直到不需要工具就输出最终答案。5. 启动验证跑通第一个请求代码写完了跑一下看看。用HumanMessage构造输入调用app.invokefrom langchain_core.messages import HumanMessage result app.invoke( { messages: [HumanMessage(content帮我算一下 (15 * 23) (48 / 6) 等于多少)], step: 0, tool_results: [], }, {recursion_limit: config[agent][recursion_limit]}, ) print(result[messages][-1].content)如果一切正常你会看到类似输出(15 × 23) (48 ÷ 6) 345 8 353模型先识别出需要调用calculator工具返回353模型再组织成自然语言回答。整个过程你可以在日志里看到两次agent节点执行和一次tools节点执行。如果你想验证模型通道是否正常可以先用 TaoToken 的模型对话页面发一条测试消息确认 Key 和模型名没问题再跑代码。地址是https://taotoken.net/chat。6. 常见报错排查我踩过的几个坑报错一AuthenticationError: Incorrect API key provided先检查.env里的TAOTOKEN_API_KEY是否加载成功。可以在代码里打印api_key[:8]确认。另外确认base_url写的是https://taotoken.net/api不要多加/v1LangChain 会自己拼。报错二model not found模型名要和 TaoToken 文档里的一致。比如你写gpt-4但实际可用的是gpt-4o就会报这个错。建议先在模型对话页面确认模型可用再填进config.toml。报错三GraphRecursionError: Recursion limit of 10 reached说明 Agent 陷入了循环通常是工具一直返回错误、模型反复重试。解决办法有两个一是把recursion_limit调大二是检查工具函数的返回值是否合理。我建议在tool_node里加日志打印每次工具调用的输入输出很快就能定位。报错四tool_calls为空但模型不输出最终答案这种情况通常是模型返回了空内容。检查temperature是否设得太高或者max_tokens太小导致输出被截断。把temperature设为 0、max_tokens调到 2048 以上通常能解决。报错五工具执行结果格式不对tool_node返回的消息必须包含tool_call_id、role: tool和content三个字段。少任何一个下一轮agent_node调用模型时都会报格式错误。这个坑我在第一次写的时候踩过排查了半天。如果你在接入过程中遇到 Key 或通道相关的问题可以直接去 TaoToken 的接入文档对照检查https://taotoken.net/doc。文档里有各语言的完整示例包括 LangChain 的配置片段。7. 下一步从最小 Agent 到可用系统跑通这个最小示例后你可以沿着几个方向继续扩展。一是加更多工具比如数据库查询、HTTP 请求、文件写入让 Agent 能处理更复杂的任务。二是引入MemorySaver做检查点实现多轮对话和中断恢复这在需要人工确认的场景很有用。三是把app用 FastAPI 包一层暴露成 HTTP 接口方便前端或其他服务调用。如果你打算长期做编码类 Agent比如自动改代码、跑测试、提交 PR可以了解一下 TaoToken 的 Coding Plan它针对长上下文和频繁调用做了优化地址是https://taotoken.net/coding-plan。对于需要反复调试 Agent 流程的场景稳定的模型通道能省不少事。代码写到这里你已经有了一个能跑的最小闭环。接下来就是不断加工具、加节点、加条件边让它越来越接近你真正想要的那个 Agent。
