今天不聊新的绘画模型也不聊本地部署整合包我们看一个更偏“工程架构”的东西Anthropic Academy 的官方课程《子智能体入门 | Introduction to Subagents》中英字幕版。如果你在用 Claude、Claude Code或者正在研究多智能体协作这门课值得花一个晚上看完。它讲的是一个很关键的问题怎么让一个“大而全”的智能体拆成多个“小而专”的子智能体各自负责一块任务再由主智能体统一调度。课程本身不长但把 Subagents 的使用场景、设计思路、边界和注意事项都覆盖了。这篇文章会做三件事先把 Subagents 的核心概念讲清楚再给出一套可复现的最小实践方案包括 SDK 接入、子智能体配置、批量任务和日志观察最后整理课程学习中容易被卡住的常见问题包括最近很多人提到的 gateway model route 路由报错。如果你是提示词工程师、AI 应用开发者或者正在做 AI 自动化流程可以直接按文中步骤跑一遍。1. 核心能力速览能力项说明课程来源Anthropic Academy 官方课程视频标题为 Introduction to Subagents语言支持英文原声配中英双语字幕讲解内容子智能体定义、适用场景、与主智能体的协作方式、权限边界、上下文设计核心技术Claude Agent SDK、多智能体协作、上下文隔离、任务委派适合人群使用 Claude / Claude Code 的开发者、提示词工程师、AI 应用架构师是否需要 GPU不需要课程和 SDK 均为云端 API 调用学习门槛需要有 Python 或 TypeScript 基础了解 LLM API 基本用法是否支持 API支持Claude Agent SDK 提供编程接口是否支持批量任务支持可循环创建子智能体或使用并行任务模式输出产物学习笔记、示例代码、可运行的 Agent 调度程序从材料看这门课不是讲概念就结束而是直接引导你写代码。Anthropic Academy 的模式通常是你打开教程页面右侧是视频左侧配套代码和文档学完就能把示例跑起来。对中文用户来说中英字幕版本可以大幅降低理解成本尤其是涉及 system prompt 设计和 tool 权限控制时能对照英文原文理解更准确。2. 什么是 Subagents为什么要有它2.1 先理解“主智能体”的困境一个智能体如果被塞进太多任务会出现三个问题。第一上下文被污染。主智能体既要规划任务又要调用工具还要处理用户消息如果中途插入大量细碎的子任务上下文窗口很快被占满而且跟主线无关的中间结果会干扰后续判断。第二模型能力被摊薄。一个系统提示词里写了“你是分析师又是翻译又是代码审查员还是文档写手”模型在每项任务上的表现都会打折扣。与其让一个智能体什么都做不如每个子智能体只专注一件事把系统提示词写深、写透。第三出错定位困难。任务一旦失败你不知道是哪一步出了问题。主智能体把所有逻辑写在一条链路上排错只能靠猜。2.2 子智能体的解决方案Subagents 的核心思路是把任务拆分每个子智能体有独立的系统提示词、独立的工具权限、独立的上下文空间。主智能体负责理解用户意图把任务分派给合适的子智能体再把结果汇总回来。这样做的好处是上下文隔离。每个子智能体只看到自己需要的信息不会被主对话中的其他内容干扰。专业分工。你可以为每个子智能体写高度针对性的 system prompt比如一个专门做代码审查一个专门写测试用例。工具权限收敛。不需要让主智能体持有全部工具子智能体按需加载。可组合。多个子智能体可以串行、并行、分层组合扩展性比单智能体好很多。2.3 课程讲到的关键设计原则《Introduction to Subagents》这门课里强调了几条原则都是工程实践中容易忽略的每个 Subagent 都应该有明确的任务描述不要含糊。给 Subagent 的上下文越精简越好只传必要字段。主智能体不要替子智能体做子任务要委派不要代劳。要为子智能体定义清晰的输出格式方便主智能体解析。子智能体不是越多越好任务简单时直接用单智能体。这些原则本身不复杂难的是在实际项目里坚持执行。课程的案例演示会告诉你同样一个任务用子智能体拆分前后输出的可维护性和稳定性差别很大。3. 适用场景与使用边界3.1 适合的场景从课程内容看Subagents 适合下面几类场景。第一研究类任务。主智能体需要查资料、读文档、对比多个来源然后输出研究报告。这种任务步骤多、信息量大适合拆成“检索子智能体”“分析子智能体”“写作子智能体”。第二编程任务。代码生成、代码审查、测试编写、README 生成可以分别交给不同子智能体避免一个智能体在“写代码”和“审代码”之间角色切换。第三批量内容处理。给每个文档创建一个独立的子智能体实例并行执行摘要、翻译、结构化提取最后汇总。这种方式比单智能体循环处理更快而且单个失败不影响整体队列。第四需要严格权限划分的企业场景。不同子智能体访问不同工具和资源主智能体只做路由降低越权风险。3.2 不适合的场景反过来如果任务本身就是简单问答或者整个流程线性且没有分支强行引入子智能体会增加调用延迟和 token 消耗没必要。3.3 安全与合规提醒无论你拿 Subagents 做什么都要注意三点授权与合规问题。如果子智能体处理的是他人作品、版权内容需要确认是否有合法授权。如果应用到人像、声音、身份信息必须落实隐私保护措施不能滥用。涉及自动决策或对外发布的场景需要对子智能体的输出做人工复核尤其是内容生成类任务模型输出不代表事实正确。技术本身是中性的但使用方式和数据来源必须合规。4. 环境准备与学习路径4.1 看课需要什么看这门课不需要本地 GPU不需要装大模型只需要能访问 Anthropic Academy 官网的浏览器。中英字幕版视频可以对照学习。基础的 Python 或 TypeScript 知识。Anthropic API Key如果跟着做 SDK 练习需要用到。4.2 跑课程示例需要什么环境假设你要在本地把课程里的 Subagents 示例跑起来推荐环境如下项目建议操作系统macOS / Linux / Windows WSLPython3.10 或更高版本Node.js18 或更高版本如使用 TypeScript包管理pip 或 npm / bunAPI KeyANTHROPIC_API_KEY 环境变量网络要求可正常访问 Anthropic API本地防火墙需放行 HTTPS 出站4.3 安装 Anthropic Agent SDKClaude Agent SDK 是跑 Subagents 示例的底层依赖。SDK 的安装方式很简单Python 环境直接 pip 安装pip install anthropic-agentsTypeScript 环境npm install anthropic-ai/claude-agent-sdk安装完成后配置环境变量。把 API Key 写入当前终端会话避免硬编码到代码文件里export ANTHROPIC_API_KEY你的_API_Key如果是 Windows PowerShell命令略有不同$env:ANTHROPIC_API_KEY你的_API_Key准备好之后先做一个最小验证检查 SDK 能否正常导入。import anthropic_agents print(SDK 导入成功)如果导入失败检查 Python 版本是否过低或者依赖是否安装完整。5. 用 Agent SDK 实现一个主从智能体示例课程的核心演示就是用 SDK 创建主智能体再让主智能体调用子智能体。下面是一个通用的最小示例具体接口以你安装的 SDK 版本为准。5.1 Python 示例主人与助手先创建一个子智能体专注做“摘要”。再创建一个主智能体负责接收用户的原始文本委派给摘要子智能体然后返回结果。import asyncio from anthropic_agents import Agent, Runner # 定义子智能体专注摘要任务 async def summarize(text: str) - str: agent Agent( namesummarizer, system_prompt( 你是一名专业的文本摘要助手。 你的任务是把用户输入的长文本压缩为 100 字以内的摘要。 不要添加原文之外的信息不要输出评价。 ) ) runner Runner(agent) result await runner.run(f请对以下文本生成摘要\n\n{text}) return result.output # 定义主智能体负责路由 async def main(): agent Agent( namerouter, system_prompt( 你是主智能体。当用户给你一段长文本时 调用摘要子智能体处理并把摘要结果返回给用户。 ), tools[summarize] ) runner Runner(agent) result await runner.run(请帮我总结这篇文章的核心观点。) print(result.output) if __name__ __main__: asyncio.run(main())这是一个骨架示例核心是让你理解两层结构主智能体不自己处理长文本而是调用子智能体工具。课程里会在这个基础上增加错误重试、多步骤编排和状态传递。5.2 TypeScript 示例并行研究与汇总如果你习惯 TypeScript也可以这么组织。下面这个示例创建两个研究子智能体主智能体等待它们各自返回结果import { Agent, Runner } from anthropic-ai/claude-agent-sdk; async function researchA(query: string): Promisestring { const agent new Agent({ name: researcher-a, systemPrompt: 你是研究助手 A负责检索技术架构方向的资料。 }); const runner new Runner(agent); const result await runner.run(研究主题${query}); return result.output; } async function researchB(query: string): Promisestring { const agent new Agent({ name: researcher-b, systemPrompt: 你是研究助手 B负责检索产品体验方向的资料。 }); const runner new Runner(agent); const result await runner.run(研究主题${query}); return result.output; } async function main() { const [outA, outB] await Promise.all([ researchA(多智能体编排), researchB(多智能体编排) ]); console.log(汇总结果); console.log(A 方向${outA}); console.log(B 方向${outB}); } main();这种并行模式在真实项目中很常见。多个子智能体互不依赖同时执行最后由主程序汇总。批量文档处理、平行市场调研、竞品分析都可以用这种模式。5.3 课程示例的通用运行方式Anthropic Academy 的配套代码通常以main.py或agent.ts为入口运行方式为python main.py或者npx tsx agent.ts运行后日志里会打印主智能体与子智能体的消息交换过程。重点观察两点主智能体是否正确选择了子智能体子智能体是否只接收了必要上下文。6. 功能测试与效果验证课程不只是讲概念更重要的是验证两件事子智能体是否真正被调用以及调用结果是否满足预期。下面给出一套可以直接套用的验证流程。6.1 测试智能体委派是否生效测试目的确认主智能体在收到复杂任务时会选择调用子智能体而不是自己做。输入素材请对这段文本做三件事1. 提取关键实体2. 生成一百字摘要3. 翻译成英文。预期结果主智能体的处理链路中出现对子智能体的调用记录而不是一次性输出全部结果。可以用日志或回调函数捕获工具调用事件。判断标准能看到子智能体的 name 出现在调用日志中且输出格式符合子智能体预设格式。常见失败主智能体没有调用子智能体直接自己完成了任务。这种情况通常是 system prompt 里没有明确“必须委派子任务”的指令需要加强路由指令描述。6.2 测试上下文隔离测试目的确认子智能体看不到主对话中无关内容。操作方式在主对话中故意插入一段与任务无关的隐私文本或随机内容然后让子智能体执行摘要任务。预期结果子智能体只处理被委派的那段文本结果中不出现无关内容。如果子智能体输出中混入了主对话里的无关信息说明上下文传传递没有做好隔离需要检查 SDK 的消息构造逻辑。6.3 测试自定义输出格式输出格式控制是多智能体项目里最容易忽视的一环。课程建议子智能体的 system prompt 里直接写明输出格式要求。你的输出必须是一个 JSON 对象包含以下字段 { summary: 摘要内容, keywords: [关键词1, 关键词2], confidence: 0~1 的置信度值 }测试时给子智能体一段非结构化文本观察它是否按 JSON 格式返回。规范化输出格式之后主智能体解析子智能体的结果会非常稳定批量任务也更方便做结果校验。6.4 测试批量任务如果是批量处理的场景可以先准备一个包含多条文本的列表循环创建子智能体任务tasks [ 文本一讲解多智能体架构。, 文本二对比消息队列的选型。, 文本三总结 RAG 的最佳实践。 ] async def run_batch(tasks): for i, task in enumerate(tasks): print(f任务 {i 1} 开始处理) result await summarize(task) print(f任务 {i 1} 结果{result}) print(---)批量模式同样要加入日志、重试与失败隔离。单个任务失败不能拖垮整个队列。7. 接口 API 与批量任务设计课程涉及的不仅是单次对话还包括如何把 Subagents 接入到自己的应用服务中。7.1 API 调用示例实际项目中你通常会把子智能体封装成一个 HTTP 接口让上层应用调用。下面给出一套通用模板接口地址和参数名需要按你自己的服务调整from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class TaskRequest(BaseModel): text: str task_type: str summary app.post(/agent/task) async def run_task(req: TaskRequest): if req.task_type summary: result await summarize(req.text) return {status: ok, result: result} return {status: error, message: unknown task type}启动服务uvicorn main:app --host 0.0.0.0 --port 8000注意接口服务如果部署在公网必须加访问鉴权最简单的做法是加 API Key 请求头。7.2 批量任务的队列思路当任务数量很大时不建议直接 for 循环串行调用也不建议无限并发。更稳妥的做法是控制并发上限。import asyncio from concurrent.futures import ThreadPoolExecutor MAX_CONCURRENCY 5 async def process_batch_with_limit(tasks): sem asyncio.Semaphore(MAX_CONCURRENCY) async def worker(task): async with sem: return await summarize(task) results await asyncio.gather( *(worker(task) for task in tasks), return_exceptionsTrue ) return results批量任务建议保存原始输入、中间日志、最终输出三份文件方便回溯。7.3 API 密钥与权限管理多智能体服务会比单智能体接触更多数据权限管理尤其重要。API Key 通过环境变量注入不写入业务代码。子智能体按最小权限分配工具不用的工具不加载。对外接口单独使用一个低权限 Key避免和主 Key 混用。日志中不要输出完整 API Key、用户敏感信息或者完整请求体。8. 上下文长度与性能观察多智能体不是完全不花成本的架构。你换来的是可维护性和专业度但同时也带来了资源开销。8.1 重点观察Token 消耗每个子智能体实例都要独立占用上下文窗口。你和主智能体之间的所有消息包括调用子智能体时的参数传递、返回结果都会计入 token 消耗。所以子智能体的输入不要传整份主对话记录只传任务相关的最小片段。8.2 重点观察任务延迟并行子智能体能缩短总耗时但也会同时产生多个 API 请求增加瞬时配额压力。如果是串行编排延迟会线性叠加。建议在服务端记录每个子智能体的起止时间和 token 用量2025-06-01 10:00:01 subagentsummary statusstarted tokens_in120 2025-06-01 10:00:08 subagentsummary statuscompleted tokens_out80通过日志可以快速定位是路由决策慢还是子智能体本身执行慢。8.3 降低开销的手段复用子智能体。相同任务不重复创建新实例用同一个子智能体处理一批同类输入。结果压缩。子智能体返回内容尽量精简主智能体不需要细节时只保留结论。提前终止。如果任务目标已达成可以直接结束不必等所有子智能体返回。8.4 进程与端口排查如果 SDK 示例以本地服务方式运行需要注意端口检查和进程清理# 查看端口占用 lsof -i :8000 # 结束占用进程替换 PID 为实际值 kill -9 PID端口冲突常见于同时启动多个示例服务解决办法是换个端口或者在启动命令里显式指定。9. 常见问题与排查方法课程学习和代码实践中下面几个问题出现率最高。9.1 常见问题排查表问题现象可能原因排查方式解决方案子智能体未被调用主智能体 system prompt 没有明确要求委派查看主智能体输出日志确认是否自行完成任务强化路由指令明确要求必须调用子智能体工具子智能体输出格式混乱没有在 system prompt 中定义输出格式检查子智能体返回内容是否符合预期结构在 system prompt 中加入 JSON 或 Markdown 模板上下文被污染主对话消息被整体传给子智能体查看子智能体日志中 tokens_in 大小只传任务相关字段精简上下文API Key 报 401ANTHROPIC_API_KEY 未设置或已失效在终端执行echo $ANTHROPIC_API_KEY重新设置环境变量SDK 提示 model route 相关错误配置了非 Anthropic 模型名称或使用了 gateway 路由但模型不在白名单内类似doesnt look like an anthropic model: expected a gateway model route reference检查 SDK 配置中的 model 字段是否用了正确模型标识使用课程指定的 Anthropic 模型名称或调整 gateway 路由配置后重试单条任务卡住无返回子智能体等待结果回调或工具执行异常查看完整 traceback 日志给子智能体调用加超时和重试机制API Key 硬编码在代码里安全意识不足搜索代码仓库里的 API Key 字符串改用环境变量并轮换已泄露的 Key9.2 关于 Gateway 路由报错的说明最近有开发者反馈自己在配置 Claude 相关 SDK 时遇到类似这样的报错doesnt look like an anthropic model: expected a gateway model route reference这个报错通常不是 SDK 坏了而是模型路由配置指向了非预期模型或者 gateway 路由中的模型标识和 Anthropic 模型不匹配。排查思路是先确认 SDK 配置里的 model 参数写的是标准 Anthropic 模型名再检查网关侧的路由指向是否对应官方模型列表。如果项目里用了自建 API 代理网关还要检查网关转发规则是否配置了正确的路由标识。9.3 失败重试设计多智能体项目的失败是常态不失败才是意外。建议在调用子智能体时加入简单的重试逻辑import time async def call_with_retry(func, max_retries3): for attempt in range(max_retries): try: return await func() except Exception as e: print(f第 {attempt 1} 次调用失败{e}) if attempt max_retries - 1: raise time.sleep(2)重试不是盲目循环。要针对超时、限流、临时网络错误做重试业务逻辑返回的错误就不要重试直接跳过或人工处理。10. 最佳实践与使用建议把课程内容转化成生产能力建议按照下面这套思路推进。10.1 第一次跑先做最小验证不要一上来就设计 10 个子智能体的大型编排。先建一个主智能体、一个子智能体跑通一次委派链路。确认日志正常、返回结果正确再逐步加角色和工具。10.2 保留一套最小可运行配置把课程里最基础的示例保存为一个独立目录作为项目模板。之后所有多智能体项目都从这套模板扩展避免每次从零搭环境。推荐目录结构subagents-demo/ ├── agents/ │ ├── summarizer.py │ └── researcher.py ├── main.py ├── .env.example ├── requirements.txt └── logs/模板里写清楚环境变量、依赖清单和启动命令方便团队其他成员直接复用。10.3 让每个子智能体只做一类事这是课程反复强调的核心原则。如果发现某个子智能体的 system prompt 里既要翻译又要绘图又要写代码说明拆分粒度不对需要重新划分职责。10.4 每次修改都做效果对比多智能体的调整往往影响下游链路。改一个子智能体的 system prompt可能让主智能体的路由决策变化。建议对每次修改保留一组固定基准测试用例比如固定的 10 条测试文本统一记录 token 消耗和输出质量改完后跑一遍对比判断改动是正向还是负向。10.5 安全与合规不能省不使用未授权数据训练或处理。不把敏感信息输入到线上第三方模型除非确认数据协议允许。对外发布的内容必须经过人工审核。涉及人脸、身份、声音等处理的子智能体必须落实授权确认机制。10.6 日志是定位问题的关键每增加一层子智能体排查难度都在上升。只有完整记录“用户输入、主智能体路由结果、子智能体输入、子智能体输出、最终回复”这五层信息才能快速定位问题。日志格式建议统一为 JSON 行方便后续接入日志分析平台{level: info, event: subagent_completed, subagent: summary, time_ms: 8200, token_in: 320, token_out: 180}10.7 Gateway 与路由配置如果你所在团队已经使用了 Anthropic Gateway 或自建路由网关子智能体和主智能体的请求会走同一套路由规则。要特别注意为子智能体单独规划模型白名单和权限组避免子智能体的模型路由和主智能体互相污染也避免权限过高导致误用工具。路由配置调整后先跑最小示例验证网关转发是否正常再上批量任务。11. 总结与下一步这门《Introduction to Subagents》课程最值得看的点不是某个具体函数而是整套“主智能体负责路由、子智能体负责执行”的工程思维。相比单智能体的长链路提示词这种设计让任务边界更清楚、上下文更干净、工具权限更可控。建议你在学完课程后先做两个验证一是跑通主智能体到子智能体的基础委派链路确认日志输出正确二是用并行子智能体跑一批文档处理任务观察 token 消耗和时间开销。最容易踩的坑有两个一个是子智能体的上下文传太厚导致 token 成本翻倍且输出被无关信息干扰另一个是主智能体路由指令写得不够明确它不调用子智能体选择自己硬做。遇到这两个问题先检查 system prompt再检查消息构造逻辑。后续可以继续扩展的方向把子智能体接入工作流引擎做成事件驱动的自动化任务比如新文档入库自动触发摘要、翻译、结构化提取再进一步可以为不同业务场景建立独立的子智能体库像工具集一样按需组合使用。把课程看完然后把这个最小示例跑通你就真正掌握了 Subagents 的基础用法。