1. 从单 Agent 到子代理协同为什么你的 Python 工作流需要拆开如果你最近在写 AI Agent大概率遇到过这种场景一个 Agent 既要读需求、又要查代码、还要写文档最后输出质量忽高忽低。问题不在模型本身而在于你把太多职责塞进了一个上下文窗口。AI Agent 架构演进的核心方向之一就是把「一个大而全的 Agent」拆成多个专精子代理再由一个主调度器负责编排。这跟软件工程里的微服务拆分是同一个逻辑职责单一边界清晰输出才稳定。子代理模式解决的是三个具体痛点。第一上下文污染。代码审查和文档撰写需要的系统提示完全不同混在一起会让模型在两种语气之间摇摆。第二并行能力缺失。单 Agent 只能串行处理子任务而多子代理可以同时跑规划、编码、测试三条线。第三模型选型僵化。规划类任务适合推理强的模型代码生成适合代码专精模型文档适合成本更低的通用模型单 Agent 没法按任务切换。注意力残差则是另一个层面的优化。传统 Transformer 每一层都把全部历史信息往上堆高层接收到的信息被逐层稀释长上下文场景下重要特征容易丢失。注意力残差让高层可以直接「回看」更早的层选择性保留关键信息在 48B 参数级别上能带来约 1.25 倍的计算效率提升。对普通开发者来说你不需要自己实现这个架构但在选型时关注这类结构优化的模型同样的算力预算下能拿到更高的推理吞吐。这篇文章要交付的是一条完整路径先用 Python 搭一个多子代理工作流再通过 TaoToken 统一 Key 和 API 通道完成调用验证最后给出可复制的配置片段和排障清单。适合已经会写 Python、想把手里的 Agent 从 Demo 推进到可用工作流的开发者。下面从环境准备开始每一步都能直接跑。2. TaoToken 前置准备统一 Key 与 API 通道配置在写多子代理代码之前先把调用通道固定下来。多 Agent 系统最麻烦的地方在于不同子 Agent 可能想用不同模型如果每个模型都单独对接一家厂商Key 管理、计费、限流会变成一团乱麻。TaoToken 的作用就是把这些模型收敛到一个 OpenAI 兼容接口后面你只需要维护一个 Base URL 和一个 API Key。先注册并拿到 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 完成账号注册后进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsole 。在控制台里找到 API Keys 页面路径是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keys 新建一个 Key 并复制保存。这个 Key 只显示一次丢了只能重建。拿到 Key 之后API 端点固定为 https://taotoken.net/api 注意这个地址不加 UTM 参数直接作为 base_url 使用。如果你用的是 OpenAI SDKbase_url 要写成 https://taotoken.net/api/v1 这种带版本号的形式具体以接入文档为准。文档地址在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc 里面有各语言 SDK 的完整示例。环境变量建议这样设置避免把 Key 硬编码进代码export TAOTOKEN_API_KEYsk-你的密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/api/v1如果你在 Windows 上用 PowerShell换成$env:TAOTOKEN_API_KEYsk-你的密钥。设置完之后可以用echo $TAOTOKEN_API_KEY确认一下输出为空说明没生效检查一下是不是写到了错误的 shell 配置文件里。模型选择方面多子代理场景建议至少准备两个模型 ID一个推理强的用于规划一个代码专精的用于生成。具体可用模型列表在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchat 里能看到也可以直接在文档里查模型 ID 对照表。把模型 ID 记下来下一步写配置的时候要用。3. 可复制配置多子代理工作流的 settings 与代码片段这一节给出可以直接复制运行的配置。先建一个项目目录然后创建配置文件。我用 JSON 格式存模型路由策略方便后续扩展{ base_url: https://taotoken.net/api/v1, api_key_env: TAOTOKEN_API_KEY, agents: { planner: { model: claude-sonnet-4-6, temperature: 0.2, system_prompt: 你是资深软件架构师负责将功能需求拆解为开发任务。严格输出 JSON 数组每个元素包含 id, title, description, files, type 字段type 只能是 code、doc、test 三者之一。不要输出任何额外说明。 }, coder: { model: gpt-5.4, temperature: 0.1, system_prompt: 你是高级后端工程师擅长在现有代码库中增量实现功能。根据任务说明和代码快照输出变更方案每段代码前标注目标文件路径使用 Markdown 代码块。 }, docwriter: { model: claude-sonnet-4-6, temperature: 0.3, system_prompt: 你是技术文档工程师将实现细节整理为易懂文档。输出包含变更概要、开发者实现说明、用户使用说明三部分。 } } }把这个文件存为agent_config.json。注意api_key_env字段指向环境变量名而不是直接写 Key这样配置文件可以安全地提交到版本库。接下来是主程序。安装依赖只需要一个包pip install openai然后创建multi_agent.pyimport json import os from typing import List, Dict from openai import OpenAI with open(agent_config.json, r, encodingutf-8) as f: CONFIG json.load(f) client OpenAI( api_keyos.getenv(CONFIG[api_key_env]), base_urlCONFIG[base_url], ) def call_agent(agent_name: str, user_prompt: str) - str: agent CONFIG[agents][agent_name] resp client.chat.completions.create( modelagent[model], messages[ {role: system, content: agent[system_prompt]}, {role: user, content: user_prompt}, ], temperatureagent[temperature], ) return resp.choices[0].message.content def planner_agent(requirement: str, repo_summary: str) - List[Dict]: prompt f功能需求\n{requirement}\n\n仓库概况\n{repo_summary}\n\n请输出 JSON 数组。 raw call_agent(planner, prompt) raw raw.strip().removeprefix(json).removeprefix().removesuffix().strip() tasks json.loads(raw) assert isinstance(tasks, list) return tasks def coder_agent(task: Dict, snapshot: str) - str: prompt f当前任务\n{json.dumps(task, ensure_asciiFalse)}\n\n代码快照\n{snapshot} return call_agent(coder, prompt) def doc_agent(tasks: List[Dict], changes: str) - str: prompt f任务列表\n{json.dumps(tasks, ensure_asciiFalse)}\n\n代码变更\n{changes} return call_agent(docwriter, prompt) def run_workflow(requirement: str, repo_summary: str, snapshot: str): tasks planner_agent(requirement, repo_summary) print(f规划出 {len(tasks)} 个任务) code_changes [] for task in tasks: if task.get(type) code: patch coder_agent(task, snapshot) code_changes.append(f## {task[id]} {task[title]}\n{patch}) merged \n\n.join(code_changes) doc doc_agent(tasks, merged) return {tasks: tasks, code: merged, doc: doc} if __name__ __main__: result run_workflow( requirement为博客系统增加 AI 推荐文章功能详情页底部展示 3 篇相关推荐提供 GET /api/recommendations 接口。, repo_summaryDjango 博客系统含 blog/models.py、blog/views.py、api/views.py。, snapshotfrom blog.models import Post, Tag\nclass Post(models.Model):\n title models.CharField(max_length200)\n tags models.ManyToManyField(Tag), ) print(result[doc])这段代码的关键设计点有三个。第一模型路由集中在 JSON 里换模型不用改代码。第二call_agent统一封装所有子代理走同一个客户端。第三Planner 的输出做了 Markdown 代码块剥离因为模型有时会习惯性包一层 json直接json.loads会报错。如果你用的是 Claude Code 这类工具做本地开发可以在项目根目录放一个.claude/settings.json把 Base URL 和 Key 配进去让工具链也走同一条通道{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥 } }注意 Claude Code 用的是ANTHROPIC_BASE_URL而不是 OpenAI 的base_url两者不要混。如果你同时用 Cline 或 CodexCline 的 MCP 配置里填 Base URL、Key、Model ID 三件套Codex 则在auth.json里配置。三者的字段名不同但指向的端点是一致的。4. 验证请求从单次调用到完整工作流跑通配置写完之后先做最小验证确认通道是通的。单独跑一次对话请求from openai import OpenAI import os client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlhttps://taotoken.net/api/v1, ) resp client.chat.completions.create( modelclaude-sonnet-4-6, messages[{role: user, content: 用一句话说明什么是子代理模式}], ) print(resp.choices[0].message.content)如果这一步能打印出正常回复说明 Key、Base URL、模型 ID 三者都对上了。如果报错先看错误类型下一节有对照表。单次调用通过后跑完整工作流python multi_agent.py预期输出分三段。第一段是规划结果类似规划出 4 个任务后面跟着任务列表。第二段是代码变更每个 code 类型任务对应一段带文件路径标注的代码块。第三段是文档包含变更概要和说明。实测下来一个中等复杂度的需求Planner 通常拆出 3 到 6 个任务其中 code 类型占一半左右。验证的时候重点看两个地方。一是 Planner 输出的 JSON 能不能被json.loads直接解析如果频繁失败说明 system prompt 里的格式约束还不够强可以在末尾加一句「只输出 JSON第一个字符必须是 [」。二是 Coder 输出的代码块有没有标注文件路径没有的话后续没法自动应用补丁需要在 prompt 里再强调一次。如果你想验证注意力残差这类新架构模型的实际表现可以在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchat 里直接对比同一个长上下文任务在不同模型上的输出质量。重点观察长文档摘要和跨段落推理这两类任务结构优化带来的差异在这类场景下最明显。对于需要长期跑 Agent 的场景比如每天定时扫描仓库、生成变更建议建议用 Coding Plan 而不是按次调用。Coding Plan 的入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-plan 适合这种持续性的编码和 Agent 任务。按次调用更适合验证和调试阶段。5. 常见报错排查401、local proxy failed 与 choices 解析失败多子代理工作流跑不起来九成问题集中在这几类报错上。下面按错误信息对照排查。401 Unauthorized。最常见的原因是 Key 没读到。先确认环境变量在当前 shell 里生效echo $TAOTOKEN_API_KEY。如果为空检查是不是写进了.bashrc但当前终端没重新加载执行source ~/.bashrc再试。如果环境变量正常检查 Key 有没有多余空格复制的时候容易带上换行。还有一种情况是 Key 被禁用或额度耗尽去控制台的 API Keys 页面确认状态。local proxy failed / connection refused。这类报错通常出现在你本地配了额外的网络层导致请求没直接打到https://taotoken.net/api。排查方法是先用 curl 直接测端点curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-6,messages:[{role:user,content:ping}]}如果 curl 能通但 Python 不通说明是 SDK 配置问题重点检查base_url有没有写错版本号。如果 curl 也不通检查本机 DNS 和防火墙设置。reading choices 报错 / KeyError: choices。这个错误说明返回的 JSON 结构里没有choices字段通常是请求本身失败了但错误信息被吞掉了。解决办法是在调用处打印完整响应resp client.chat.completions.create(...) print(resp.model_dump_json(indent2))常见触发原因是模型 ID 写错。比如把claude-sonnet-4-6写成了claude-sonnet-4.6或者用了平台上不存在的模型名。去文档里核对准确的模型 ID注意大小写和连字符。OAuth 相关报错。如果你在 Claude Code 或类似工具里看到 OAuth 失败说明工具在尝试走账号授权而不是 API Key。检查.claude/settings.json里是不是同时配了ANTHROPIC_API_KEY和 OAuth 相关字段两者冲突时优先走 OAuth。把 OAuth 字段删掉只保留 Base URL 和 API Key。Planner 输出解析失败。这不是网络问题是模型输出格式问题。表现是json.loads抛异常。处理办法是在解析前做清洗去掉 Markdown 代码块标记再尝试解析。如果还是失败把 temperature 降到 0.1并在 system prompt 里加一句「不要输出任何解释性文字」。子代理之间上下文串味。表现是 Coder 输出了文档语气或者 DocWriter 开始写代码。原因是 system prompt 边界不够清晰。每个子代理的 system prompt 里要明确写「你只负责 X不要做 Y」。另外检查一下是不是把上一个子代理的输出直接拼进了下一个的 user prompt 而没有加分隔标记。排查顺序建议固定下来先 curl 测端点再单次 Python 调用最后跑完整工作流。这样能把问题定位在网络层、SDK 层还是业务逻辑层避免一上来就改代码。6. 从架构理解到可运行 Demo 的落地路径把这条路径走完你手里就有了一个能跑的多子代理工作流配置文件管模型路由主程序管编排TaoToken 管统一通道。接下来可以按需扩展。想加测试环节就在 JSON 里加一个tester子代理system prompt 写「你是测试工程师根据代码变更生成单元测试」。想并行执行把run_workflow里的 for 循环换成concurrent.futures.ThreadPoolExecutor每个 code 任务提交一个 future。想接本地文件系统在 Coder 之前加一步向量检索只把相关文件片段塞进上下文避免上下文爆炸。注意力残差这类架构优化短期内不需要自己实现但选型时值得关注。同样的任务结构优化过的模型在长上下文场景下输出更稳推理成本也更低。你可以在模型对话页面里用同一段长文档做对比测试观察摘要质量和关键信息保留率。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc 里面有各语言 SDK 的完整参数说明和模型 ID 列表。API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keys 。先把单次调用跑通再把子代理逐个接上最后串成工作流这个顺序能帮你少踩很多坑。