1. 从 ReAct 到 Planning Agent为什么复杂任务需要先规划再执行如果你已经用 LangChain 或 LangGraph 写过 ReAct Agent大概率经历过这样的场景让它做一份行业调研它搜了两轮就开始跑偏要么重复调用同一个搜索工具要么漏掉对比环节最后输出一份结构松散的内容。这不是模型不够聪明而是 ReAct 的机制决定的——它每一轮只回答“下一步做什么”没有全局视角。Planning Agent 要解决的就是这个问题。它的核心思路是先让模型把任务拆成有序的步骤列表再逐步执行。这种模式叫 Plan-and-Execute最早在 2023 年前后被系统化提出如今已经成为复杂 Agent 系统的主流架构之一。适合谁适合正在做多步骤自动化、研究报告生成、代码工程 Agent、办公流程编排的开发者。如果你只做单次天气查询或简单问答ReAct 完全够用不必上 Planning。我试过用同一个模型分别跑 ReAct 和 Plan-and-Execute 做“对比两个 Agent 平台差异”的任务ReAct 版本出现了三次重复搜索和一次主题漂移而 Planning 版本先输出了五步计划执行过程稳定得多。代价是 Token 消耗大约多了 30% 到 50%延迟也更高。所以选型的关键不是哪个更好而是任务复杂度是否值得这份开销。本文会用 LangGraph 搭一个最小可运行的 Planner 骨架并通过 TaoToken 统一 Key 接入模型通道给出可复制的 config.toml 和 settings.json 配置片段最后跑一次完整验证确认 Planner 节点能正常产出结构化计划。全程不需要你切换多个平台的 Key一个统一入口就能跑通。2. TaoToken 统一 Key 前置准备config.toml 与 settings.json 配置片段在写 LangGraph 代码之前先把模型通道配好。TaoToken 的作用是提供一个统一的 API 入口让你用同一个 Key 访问多种模型省去在多个平台之间切换的麻烦。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。你需要先拿到一个 API Key。进入控制台创建即可https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后在 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后建议不要硬编码在代码里而是通过配置文件或环境变量注入。下面给出两个配置片段。第一个是 config.toml适合放在项目根目录供 Python 侧读取# config.toml [llm] provider openai-compatible base_url https://taotoken.net/api api_key sk-your-taotoken-key model gpt-4o-mini temperature 0.2 max_tokens 2048 [planner] max_steps 8 allow_replan false第二个是 settings.json适合 Node 侧或需要 JSON 配置的工具链{ llm: { baseUrl: https://taotoken.net/api, apiKey: sk-your-taotoken-key, modelId: gpt-4o-mini, temperature: 0.2 }, planner: { maxSteps: 8, allowReplan: false } }这里三个关键字段必须对齐Base URL 填 https://taotoken.net/api Key 填你生成的 sk- 开头字符串Model ID 填你要用的模型名。如果你后面用 Claude Code 或 Cline 这类工具也是同样的三件套逻辑。配置完成后可以用一条 curl 命令快速验证通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-your-taotoken-key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复 OK}] }如果返回内容里包含 choices 字段且 message.content 有值说明通道正常。这一步很重要因为后面 LangGraph 报错时你需要先排除是通道问题还是代码问题。3. 用 LangGraph 搭建 Planner 骨架State、Node 与可复制代码LangGraph 适合做 Planning Agent 的原因很直接它原生支持 State、多 Node、Conditional Edge 和长流程控制。Planning 的本质就是“复杂状态 多步骤执行”这两者天然匹配。下面我们搭一个最小骨架只包含 Planner 节点和 Executor 节点先确认 Planner 能产出计划。先安装依赖pip install langgraph langchain-openai然后写核心代码。State 定义如下包含用户任务、计划列表、当前步骤索引和执行结果# planner_agent.py import json from typing import TypedDict, List from langgraph.graph import StateGraph, START, END from langchain_openai import ChatOpenAI class PlanState(TypedDict): task: str plan: List[str] current_step: int results: List[str] llm ChatOpenAI( base_urlhttps://taotoken.net/api, api_keysk-your-taotoken-key, modelgpt-4o-mini, temperature0.2, ) PLANNER_PROMPT 你是一个任务规划器。请把用户任务拆解为 3 到 6 个有序步骤。 只输出 JSON 数组每个元素是一个步骤描述不要输出其他内容。 用户任务{task} def planner_node(state: PlanState) - PlanState: resp llm.invoke(PLANNER_PROMPT.format(taskstate[task])) content resp.content.strip() if content.startswith(): content content.split()[1] if content.startswith(json): content content[4:] plan json.loads(content) return {plan: plan, current_step: 0, results: []} def executor_node(state: PlanState) - PlanState: step state[plan][state[current_step]] resp llm.invoke(f请执行以下步骤并给出结果{step}) results state[results] [resp.content] return {results: results, current_step: state[current_step] 1} def should_continue(state: PlanState) - str: if state[current_step] len(state[plan]): return end return execute builder StateGraph(PlanState) builder.add_node(planner, planner_node) builder.add_node(executor, executor_node) builder.add_edge(START, planner) builder.add_conditional_edges(planner, should_continue, {execute: executor, end: END}) builder.add_conditional_edges(executor, should_continue, {execute: executor, end: END}) graph builder.compile()这段代码里planner_node 负责生成计划executor_node 负责逐步执行should_continue 控制循环终止。注意 planner 的输出解析做了简单的 markdown 代码块剥离因为模型有时会把 JSON 包在 json 里。如果你用的模型输出格式不稳定可以在 prompt 里加一句“不要使用 markdown 代码块”。运行入口if __name__ __main__: result graph.invoke({ task: 对比 DeepSeek 和 OpenAI 的 Agent 平台差异, plan: [], current_step: 0, results: [], }) print(计划, result[plan]) print(执行结果数, len(result[results]))到这里Planner 骨架就搭好了。你可以先只跑 planner_node确认计划输出正常再打开 executor 循环。4. 验证请求与成功结果确认 Planner 节点正常产出计划配置和代码都就绪后跑一次完整验证。执行python planner_agent.py预期看到类似输出计划 [搜索 DeepSeek Agent 平台的核心能力, 搜索 OpenAI Agent 平台的核心能力, 提取两者的功能差异点, 对比价格与模型支持, 输出总结] 执行结果数 5如果计划列表有 3 到 6 条且执行结果数与计划数一致说明 Planner 节点和 Executor 循环都正常。这一步的关键是确认 Planner 输出的 JSON 能被正确解析。如果解析失败你会看到 json.JSONDecodeError这时候先打印 resp.content 看模型实际返回了什么。你也可以单独验证 Planner 节点不跑 Executorfrom planner_agent import planner_node state {task: 帮我做一份 AI Agent 行业调研报告, plan: [], current_step: 0, results: []} out planner_node(state) print(out[plan])预期输出是一个包含 4 到 6 个步骤的列表例如搜索行业趋势、分析主要公司、对比产品能力、生成总结报告。如果这一步正常说明 TaoToken 通道、LangGraph 状态流转、JSON 解析三个环节都通了。实测下来gpt-4o-mini 在这个任务上的计划质量已经够用步骤粒度适中不会太粗也不会太细。如果你需要更细的拆解可以把 max_steps 调到 10并在 prompt 里要求“每个步骤不超过 20 字”。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth跑 Planning Agent 时报错大多集中在通道和解析两个环节。下面按真实报错逐一排查。401 Unauthorized。这是最常见的通常是 Key 没填对或没带上。检查 config.toml 或代码里的 api_key 是否是 sk- 开头以及是否有多余空格。如果你用的是环境变量确认echo $TAOTOKEN_API_KEY有值。另外注意 Base URL 必须是 https://taotoken.net/api 不要多加 /v1 或漏掉协议头。local proxy failed 或 connection refused。这类报错说明请求根本没发出去通常是本地网络配置或代理设置干扰。先确认你能用 curl 直接访问 https://taotoken.net/api 如果 curl 也失败检查本机 DNS 和防火墙。如果 curl 成功但 Python 失败检查是否有 HTTP_PROXY 环境变量被设置可以临时unset HTTP_PROXY HTTPS_PROXY再跑。reading choices 报错比如 KeyError: choices 或 TypeError: NoneType object is not subscriptable。这说明返回体里没有 choices 字段通常是模型名写错或通道返回了错误信息。先打印完整 resp 看内容。如果返回的是 error 字段检查 model ID 是否拼写正确。TaoToken 支持的模型名以控制台文档为准不要凭记忆填。OAuth 相关报错比如 invalid_grant 或 token expired。如果你用的是 Claude Code 或 Cline 这类工具OAuth 流程和 API Key 是两套机制。用 TaoToken 统一 Key 时应该走 API Key 模式不要触发 OAuth 登录。在 Claude Code 里配置时Base URL 填 https://taotoken.net/api Key 填 sk- 字符串Model ID 填对应模型名三件套缺一不可。如果工具强制走 OAuth检查是否选错了认证方式。JSON 解析失败报 json.decoder.JSONDecodeError。这是 Planner 输出格式问题不是通道问题。解决办法是在 prompt 里明确要求“只输出 JSON 数组不要 markdown 代码块”或者在解析前做更鲁棒的清洗。也可以换一个指令遵循能力更强的模型。排查顺序建议先 curl 验证通道再单独跑 planner_node 验证解析最后跑完整图验证循环。这样能快速定位问题在哪一层。6. 从 Planner 骨架到完整 Planning Agent下一步怎么走现在你已经有了一个能产出计划的 Planner 骨架并且通过 TaoToken 统一 Key 跑通了模型通道。接下来可以往几个方向扩展加入 replan 机制当某一步执行失败时让 Planner 重新生成后续步骤加入工具调用让 Executor 不只是调模型而是真正去搜索、读文件、写代码加入人工审核节点在计划生成后暂停等确认再执行。如果你要长期跑编码类 Agent 或复杂自动化流程可以了解一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合持续性的开发任务。如果只是想先验证模型对话效果可以用模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到配置问题可以先查这里。一个实用技巧Planner 的 prompt 里加上“每个步骤必须是一个可独立执行的动作”能显著减少“分析并总结”这种模糊步骤。另外把 max_steps 限制在 8 以内避免计划过长导致执行阶段 Token 爆炸。如果你发现 Executor 某一步输出太长可以在 executor_node 里对结果做截断只保留前 500 字再传给下一步。最后提醒一点Planning Agent 的稳定性很大程度取决于 Planner 的输出质量。先用小任务验证计划结构再逐步放大任务复杂度比一上来就跑大任务更容易定位问题。
1. 从 ReAct 到 Planning Agent为什么复杂任务需要先规划再执行如果你已经用 LangChain 或 LangGraph 写过 ReAct Agent大概率经历过这样的场景让它做一份行业调研它搜了两轮就开始跑偏要么重复调用同一个搜索工具要么漏掉对比环节最后输出一份结构松散的内容。这不是模型不够聪明而是 ReAct 的机制决定的——它每一轮只回答“下一步做什么”没有全局视角。Planning Agent 要解决的就是这个问题。它的核心思路是先让模型把任务拆成有序的步骤列表再逐步执行。这种模式叫 Plan-and-Execute最早在 2023 年前后被系统化提出如今已经成为复杂 Agent 系统的主流架构之一。适合谁适合正在做多步骤自动化、研究报告生成、代码工程 Agent、办公流程编排的开发者。如果你只做单次天气查询或简单问答ReAct 完全够用不必上 Planning。我试过用同一个模型分别跑 ReAct 和 Plan-and-Execute 做“对比两个 Agent 平台差异”的任务ReAct 版本出现了三次重复搜索和一次主题漂移而 Planning 版本先输出了五步计划执行过程稳定得多。代价是 Token 消耗大约多了 30% 到 50%延迟也更高。所以选型的关键不是哪个更好而是任务复杂度是否值得这份开销。本文会用 LangGraph 搭一个最小可运行的 Planner 骨架并通过 TaoToken 统一 Key 接入模型通道给出可复制的 config.toml 和 settings.json 配置片段最后跑一次完整验证确认 Planner 节点能正常产出结构化计划。全程不需要你切换多个平台的 Key一个统一入口就能跑通。2. TaoToken 统一 Key 前置准备config.toml 与 settings.json 配置片段在写 LangGraph 代码之前先把模型通道配好。TaoToken 的作用是提供一个统一的 API 入口让你用同一个 Key 访问多种模型省去在多个平台之间切换的麻烦。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。你需要先拿到一个 API Key。进入控制台创建即可https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后在 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后建议不要硬编码在代码里而是通过配置文件或环境变量注入。下面给出两个配置片段。第一个是 config.toml适合放在项目根目录供 Python 侧读取# config.toml [llm] provider openai-compatible base_url https://taotoken.net/api api_key sk-your-taotoken-key model gpt-4o-mini temperature 0.2 max_tokens 2048 [planner] max_steps 8 allow_replan false第二个是 settings.json适合 Node 侧或需要 JSON 配置的工具链{ llm: { baseUrl: https://taotoken.net/api, apiKey: sk-your-taotoken-key, modelId: gpt-4o-mini, temperature: 0.2 }, planner: { maxSteps: 8, allowReplan: false } }这里三个关键字段必须对齐Base URL 填 https://taotoken.net/api Key 填你生成的 sk- 开头字符串Model ID 填你要用的模型名。如果你后面用 Claude Code 或 Cline 这类工具也是同样的三件套逻辑。配置完成后可以用一条 curl 命令快速验证通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-your-taotoken-key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复 OK}] }如果返回内容里包含 choices 字段且 message.content 有值说明通道正常。这一步很重要因为后面 LangGraph 报错时你需要先排除是通道问题还是代码问题。3. 用 LangGraph 搭建 Planner 骨架State、Node 与可复制代码LangGraph 适合做 Planning Agent 的原因很直接它原生支持 State、多 Node、Conditional Edge 和长流程控制。Planning 的本质就是“复杂状态 多步骤执行”这两者天然匹配。下面我们搭一个最小骨架只包含 Planner 节点和 Executor 节点先确认 Planner 能产出计划。先安装依赖pip install langgraph langchain-openai然后写核心代码。State 定义如下包含用户任务、计划列表、当前步骤索引和执行结果# planner_agent.py import json from typing import TypedDict, List from langgraph.graph import StateGraph, START, END from langchain_openai import ChatOpenAI class PlanState(TypedDict): task: str plan: List[str] current_step: int results: List[str] llm ChatOpenAI( base_urlhttps://taotoken.net/api, api_keysk-your-taotoken-key, modelgpt-4o-mini, temperature0.2, ) PLANNER_PROMPT 你是一个任务规划器。请把用户任务拆解为 3 到 6 个有序步骤。 只输出 JSON 数组每个元素是一个步骤描述不要输出其他内容。 用户任务{task} def planner_node(state: PlanState) - PlanState: resp llm.invoke(PLANNER_PROMPT.format(taskstate[task])) content resp.content.strip() if content.startswith(): content content.split()[1] if content.startswith(json): content content[4:] plan json.loads(content) return {plan: plan, current_step: 0, results: []} def executor_node(state: PlanState) - PlanState: step state[plan][state[current_step]] resp llm.invoke(f请执行以下步骤并给出结果{step}) results state[results] [resp.content] return {results: results, current_step: state[current_step] 1} def should_continue(state: PlanState) - str: if state[current_step] len(state[plan]): return end return execute builder StateGraph(PlanState) builder.add_node(planner, planner_node) builder.add_node(executor, executor_node) builder.add_edge(START, planner) builder.add_conditional_edges(planner, should_continue, {execute: executor, end: END}) builder.add_conditional_edges(executor, should_continue, {execute: executor, end: END}) graph builder.compile()这段代码里planner_node 负责生成计划executor_node 负责逐步执行should_continue 控制循环终止。注意 planner 的输出解析做了简单的 markdown 代码块剥离因为模型有时会把 JSON 包在 json 里。如果你用的模型输出格式不稳定可以在 prompt 里加一句“不要使用 markdown 代码块”。运行入口if __name__ __main__: result graph.invoke({ task: 对比 DeepSeek 和 OpenAI 的 Agent 平台差异, plan: [], current_step: 0, results: [], }) print(计划, result[plan]) print(执行结果数, len(result[results]))到这里Planner 骨架就搭好了。你可以先只跑 planner_node确认计划输出正常再打开 executor 循环。4. 验证请求与成功结果确认 Planner 节点正常产出计划配置和代码都就绪后跑一次完整验证。执行python planner_agent.py预期看到类似输出计划 [搜索 DeepSeek Agent 平台的核心能力, 搜索 OpenAI Agent 平台的核心能力, 提取两者的功能差异点, 对比价格与模型支持, 输出总结] 执行结果数 5如果计划列表有 3 到 6 条且执行结果数与计划数一致说明 Planner 节点和 Executor 循环都正常。这一步的关键是确认 Planner 输出的 JSON 能被正确解析。如果解析失败你会看到 json.JSONDecodeError这时候先打印 resp.content 看模型实际返回了什么。你也可以单独验证 Planner 节点不跑 Executorfrom planner_agent import planner_node state {task: 帮我做一份 AI Agent 行业调研报告, plan: [], current_step: 0, results: []} out planner_node(state) print(out[plan])预期输出是一个包含 4 到 6 个步骤的列表例如搜索行业趋势、分析主要公司、对比产品能力、生成总结报告。如果这一步正常说明 TaoToken 通道、LangGraph 状态流转、JSON 解析三个环节都通了。实测下来gpt-4o-mini 在这个任务上的计划质量已经够用步骤粒度适中不会太粗也不会太细。如果你需要更细的拆解可以把 max_steps 调到 10并在 prompt 里要求“每个步骤不超过 20 字”。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth跑 Planning Agent 时报错大多集中在通道和解析两个环节。下面按真实报错逐一排查。401 Unauthorized。这是最常见的通常是 Key 没填对或没带上。检查 config.toml 或代码里的 api_key 是否是 sk- 开头以及是否有多余空格。如果你用的是环境变量确认echo $TAOTOKEN_API_KEY有值。另外注意 Base URL 必须是 https://taotoken.net/api 不要多加 /v1 或漏掉协议头。local proxy failed 或 connection refused。这类报错说明请求根本没发出去通常是本地网络配置或代理设置干扰。先确认你能用 curl 直接访问 https://taotoken.net/api 如果 curl 也失败检查本机 DNS 和防火墙。如果 curl 成功但 Python 失败检查是否有 HTTP_PROXY 环境变量被设置可以临时unset HTTP_PROXY HTTPS_PROXY再跑。reading choices 报错比如 KeyError: choices 或 TypeError: NoneType object is not subscriptable。这说明返回体里没有 choices 字段通常是模型名写错或通道返回了错误信息。先打印完整 resp 看内容。如果返回的是 error 字段检查 model ID 是否拼写正确。TaoToken 支持的模型名以控制台文档为准不要凭记忆填。OAuth 相关报错比如 invalid_grant 或 token expired。如果你用的是 Claude Code 或 Cline 这类工具OAuth 流程和 API Key 是两套机制。用 TaoToken 统一 Key 时应该走 API Key 模式不要触发 OAuth 登录。在 Claude Code 里配置时Base URL 填 https://taotoken.net/api Key 填 sk- 字符串Model ID 填对应模型名三件套缺一不可。如果工具强制走 OAuth检查是否选错了认证方式。JSON 解析失败报 json.decoder.JSONDecodeError。这是 Planner 输出格式问题不是通道问题。解决办法是在 prompt 里明确要求“只输出 JSON 数组不要 markdown 代码块”或者在解析前做更鲁棒的清洗。也可以换一个指令遵循能力更强的模型。排查顺序建议先 curl 验证通道再单独跑 planner_node 验证解析最后跑完整图验证循环。这样能快速定位问题在哪一层。6. 从 Planner 骨架到完整 Planning Agent下一步怎么走现在你已经有了一个能产出计划的 Planner 骨架并且通过 TaoToken 统一 Key 跑通了模型通道。接下来可以往几个方向扩展加入 replan 机制当某一步执行失败时让 Planner 重新生成后续步骤加入工具调用让 Executor 不只是调模型而是真正去搜索、读文件、写代码加入人工审核节点在计划生成后暂停等确认再执行。如果你要长期跑编码类 Agent 或复杂自动化流程可以了解一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合持续性的开发任务。如果只是想先验证模型对话效果可以用模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到配置问题可以先查这里。一个实用技巧Planner 的 prompt 里加上“每个步骤必须是一个可独立执行的动作”能显著减少“分析并总结”这种模糊步骤。另外把 max_steps 限制在 8 以内避免计划过长导致执行阶段 Token 爆炸。如果你发现 Executor 某一步输出太长可以在 executor_node 里对结果做截断只保留前 500 字再传给下一步。最后提醒一点Planning Agent 的稳定性很大程度取决于 Planner 的输出质量。先用小任务验证计划结构再逐步放大任务复杂度比一上来就跑大任务更容易定位问题。
