最近一直在折腾 Google ADK 的 Agent 开发身边好几个做 AI 应用的开发者朋友也都在问我同一个问题ADK 里 Skill 到底怎么组织才不乱上手之后很容易遇到一个尴尬的阶段——Agent 的编排逻辑写在代码里业务能力散在各个模块里跑起来能出结果但每加一个功能就想重构一次。这种状态我太熟悉了。Skill 是 ADK 里让 Agent 获得特定能力的核心单元说白了就是把“会做某件事”的能力封装成可复用的组件。同一件事用不同的 Skill 设计模式去写后续维护成本、扩展灵活性、可调试性完全是两回事。这篇教程我把实践中沉淀下来的 5 种 Skill 设计模式整理出来配合可直接照搬的代码骨架、触发逻辑、参数设计和一个完整的串联示例帮你跳过我自己踩过的那些坑。适合两类人看一类是刚接触 ADK、想知道 Skill 原理和写法的初学者另一类是已经能跑通简单 Agent、但觉得项目结构越来越乱的开发者。这篇内容把 Skill 组织方式从简单到复杂拉出一条完整谱系你可以直接对照自己的场景挑一个来用。1. 为什么 Skill 设计模式值得单独拿出来讲很多人第一次接触 ADK 时会觉得 Skill 不就是“给 Agent 写的一段工具函数”吗甚至直接把业务逻辑和 Agent 控制逻辑写在一起。头两个 Demo 没问题一旦 Agent 要处理五六个业务域这种写法立刻会演变成维护噩梦。Skill 设计模式解决的核心问题有两个第一能力边界清晰化——Agent 知道自己能调用哪些能力、不能调用哪些能力而不是把所有逻辑揉成一个巨型 Prompt第二能力可组合化——同一个 Skill 可以被不同的 Agent 复用可以组合成更复杂的流程而不是每个新 Agent 都重新实现一遍。我见过一个模拟项目最初把所有业务逻辑全部塞进一个 5000 多字的系统提示词里效果还不错但每次改需求都像是在拆炸弹。后来把业务能力拆成了几个 SkillAgent 的主提示词从 5000 字降到了 600 字行为反而更稳定了。Skill 在 ADK 里的定位相当于给 Agent 装上可插拔的“业务感知层”。5 种设计模式本质上是5种不同的“能力封装策略”。选对模式你的 Agent 架构会越做越顺手选错后期每扩展一个功能都要重构。2. 五种 Skill 设计模式的核心思路和选型逻辑我总结了实践中最高频使用的 5 种 Skill 设计模式它们构成了一个从简单到复杂的完整谱系。每种模式我都给出了适用场景、核心代码骨架和关键参数说明。2.1 模式一JSON Schema 约束模式Skill as Schema核心思路不写完整的业务逻辑只定义输入输出的 JSON Schema让模型根据 Schema 生成结构化的数据。这种模式适用于“信息抽取、格式转换、数据整理”这一类偏纯推理的任务。场景举例需要从用户输入的会议记录中提取时间、地点、行动项。业务逻辑很轻但结构要求很严。# skill_schema.py - JSON Schema约束模式 from google.adk import Skill, schema SOFTWARE_ISSUE_SCHEMA schema.Schema( typeobject, properties{ has_issue: schema.Schema(typeboolean, description是否发现异常), issue_type: schema.Schema(typestring, enum[bug, performance, security]), summary: schema.Schema(typestring, description一句话总结), }, required[has_issue, summary] ) issue_skill Skill( nameissue_checker, description检查代码提交中是否存在潜在问题, input_schemaSOFTWARE_ISSUE_SCHEMA, )选型逻辑这种模式最大的好处是零业务代码完全依赖模型的结构化推理能力。Schema 的约束天然抵御格式漂移问题。代价是它无法执行真正的动作——不能调 API、不能改数据。它适合的是“判题”和“提取”类任务不适合“执行”类任务。实操里Schema 的字段描述写得越具体模型生成的准确性越高。比如description里明确“是否发现异常”比只写“状态”好用得多。2.2 模式二Function Call 包装模式Skill as Tools核心思路把已有的 Python 函数包装成 Skill 暴露给 Agent。这是最实用、使用频率最高的模式适合所有能写成确定逻辑的操作用例。场景举例给 Agent 提供一个查询数据库的函数一个调用外卖下单 API 的函数一个读取本地文件目录的函数。每个函数本质上是已有的内部服务代码。# skill_function.py - Function Call包装模式 import random from google.adk import Skill def get_restaurant_discount(name: str) - str: 查询某家餐厅的折扣信息 discounts { 老王饺子馆: 周一全单82折, 川香楼: 满100减30, } return discounts.get(name, 暂无信息) def estimate_delivery_time(shop_name: str, distance_km: float) - str: 基于距离估算外卖预计送达时间 base_time 20 int(distance_km * 8) return f预计送达{base_time} 分钟 restaurant_skill Skill( namerestaurant_query, description查询餐厅折扣和预计送达时间, tools[ get_restaurant_discount, estimate_delivery_time, ], )关键细节函数 docstring 不是写给人看的备注是模型判断“何时调用这个 Tool”的主要依据。我见过大量失败案例原因就是 docstring 写得太抽象模型不知道该在什么场景下触发它。docstring 要写清楚“功能是什么、需要什么参数、输出什么”把这个写到位Skill 的可用率会有明显提升。选型逻辑包装模式的本质是把验证过、测试过的逻辑交给程序执行让 Agent 只负责“决策何时调用”不负责“具体怎么实现”。这避免了模型幻觉污染业务结果的路径。它也是目前生产环境里部署最广泛的一种模式原因是可控性强、可调试性高。2.3 模式三Few-shot 引导模式Skill as Prompt核心思路Skill 的内容主要是高质量样例让模型通过模仿样例来完成推理和输出。场景举例写一个“情感分析” Skill。与其用复杂的规则去给评论文本打分不如给模型展示 3-5 个“文本 → 情感标签 → 置信度”的优质样例让它按照同样格式输出。# skill_prompt.py - Few-shot引导模式 from google.adk import Skill REVIEW_EXAMPLES [ { input: 等了四十分钟还没上菜服务员态度还差, output: {\sentiment\: \negative\, \confidence\: 0.97}, }, { input: 菜量很大价格实惠下次还会来, output: {\sentiment\: \positive\, \confidence\: 0.94}, }, { input: 环境不错味道中规中矩, output: {\sentiment\: \neutral\, \confidence\: 0.78}, }, ] review_skill Skill( namereview_analyzer, description分析用户评论的情感倾向输出JSON格式结果, examplesREVIEW_EXAMPLES, output_format{sentiment: positive/negative/neutral, confidence: 0.0-1.0}, )实操心得这种模式的关键在于样例质量远大于样例数量。3 个边界清晰的样例效果比 20 个含糊样例好得多。样例要覆盖不同难度层次包括最常见的类型、临界值和容易混淆的情形。那为什么还要把它单独列为一种设计模式因为它解耦了“专业知识”与“模型权重”。领域专家不需要懂模型原理只需要提供高质量的输入输出对就能让 Agent 在该领域表现出色。代价是输出稳定性弱于确定性代码适合对格式要求不苛刻、语义判断为主的场景。2.4 模式四顺序工作流模式Skill as Workflow核心思路把多个 Tool 或子 Skill 编排成固定的前后顺序让 Agent 在一条固定的流水线上完成任务。典型场景是“先搜索、再分析、最后总结”的任务流程。实现方式有两种一种是 Skill 内部写逻辑用代码控制调用顺序另一种是在 Prompt 中给定顺序约束让模型按顺序执行。个人推荐前者——用Sequencer 机制显式定义顺序。# skill_workflow.py - 顺序工作流模式 from google.adk import Skill, Agent, Tool def fetch_stock_price(code: str) - str: 获取某股票的最新收盘价 price_map {ROUTE66: 310.50, TECHGO: 88.20} return price_map.get(code, 0.00) def fetch_news(code: str) - str: 获取某股票最近3条重要新闻 return f{code} 发布三季度财报营收同比增长18%净利润率有所收窄 def analyze(code: str) - str: 基于价格和新闻生成综合研判 price fetch_stock_price(code) news fetch_news(code) return f价格: {price}; 新闻: {news}; 结论: 结合基本面保持中性偏乐观。 agent Agent( namestock_reporter, description股票综合分析, tools[ fetch_stock_price, fetch_news, analyze, ], instruction依次调用工具获取价格和新闻再生成分析禁止跳步。 )关键细节工作流模式要注意“步间依赖”。如果后一步需要前一步的输出作为输入务必在工具函数内部做参数透传而不是让模型自己“记住”上一步结果。模型记忆并不可靠但函数签名是可靠的。选型逻辑顺序工作流把一个复杂的多步任务拆成若干个简单子任务每一步的可观测性和可追踪性都显著增强。其中任意一步失败都可以精确定位到具体环节。代价是灵活性降低——它不擅长应对“步骤次序不固定”的任务。2.5 模式五子 Agent 委托模式Skill as Delegation核心思路Skill 不只是工具集还可以是一个拥有自己记忆、工具链和状态的子 Agent。父 Agent 把复杂任务整体委托给专门化的子 Agent由后者独立完成。场景举例做一个售后客服 Agent。主 Agent 负责理解用户意图遇到退款问题转给“退款专员子 Agent”遇到技术故障转给“技术排障子 Agent”。# skill_delegation.py - 子Agent委托模式 from google.adk import Agent, Skill refund_agent Agent( namerefund_specialist, description专门处理退款申请和退款进度查询包含对接支付渠道的Tool, instruction你是退款专员先核实订单编号再查询退款状态耐心处理用户的退款疑问。, tools[query_refund_status, submit_refund_request], ) skill_troubleshoot Skill( nametech_support, description协议配置、K线显示延迟、策略信号未触发等操作类问题, tools[run_diagnostics, get_faq_answer], ) def route_by_intent(user_msg: str) - str: if any(k in user_msg for k in [退款, 退货, 赔付]): return debug_agent return refund_specialist root_agent Agent( namecustomer_service, description客服总入口, sub_agents[refund_agent], skills[skill_troubleshoot], dispatch_functionroute_by_intent, )选型逻辑这种模式是扩展能力边界最强的方案。子 Agent 可以拥有不同的温度参数、不同的模型、不同的系统提示彼此之间隔离状态互不干扰。当主 Agent 的业务分支很多时这个模式能把复杂度从“一个大泥球”变成“多个独立小模块”。代价是需要处理好委托边界。父 Agent 要能正确判断“这个任务该交给谁”子 Agent 要能明确知道自己负责的边界。如果路由逻辑混乱效果不如直接把所有逻辑写在一个 Agent 里。2.6 五种模式怎么选设计模式核心封装对象适合场景灵活性稳定性推荐优先级JSON Schema 约束数据结构信息抽取、格式转换中高简单任务优先Function Call 包装业务函数已有逻辑、确定操作中最高生产首选Few-shot 引导样例对语义理解、风格生成高中语义场景优先顺序工作流步骤序列固定流水线、多步编排低高流程复杂优先子 Agent 委托子系统多业务域、并行处理最高中系统扩展优先选型的原则一句话能用确定性代码解决的就不要交给模型发挥能拆开的业务就不要揉在一起。没有最好的模式只有当前阶段最合适的模式。3. 手把手实操从零构建一个“智能会议纪要与周报生成”Agent为了把 5 种模式串起来我用一个模拟项目完整走一遍流程做一个“会议纪要与周报自动生成助手”支持从用户输入的会议信息中提取关键字段然后调用业务系统生成日报摘要再按固定模板输出周报。这个项目覆盖了 Schema 约束、Function Call 包装、Few-shot 引导和顺序工作流四种模式非常适合练手。3.1 项目结构和 Skill 组织方式推荐目录结构meeting_report_agent/ ├── app.py ├── skills/ │ ├── __init__.py │ ├── extraction_skill.py # 模式一信息抽取Schema约束 │ ├── summary_skill.py # 模式三总结生成Few-shot引导 │ ├── database_skill.py # 模式二数据库写入Function Call包装 │ └── weekly_flow.py # 模式四周报流程顺序工作流 ├── data/ │ └── meetings.db3.2 逐步实现四个 Skill第一步创建日志提取 SkillSchema 约束# skills/extraction_skill.py from google.adk import Skill, schema MEETING_SCHEMA schema.Schema( typeobject, properties{ title: schema.Schema(typestring, description会议标题), date: schema.Schema(typestring, description会议日期格式YYYY-MM-DD), participants: schema.Schema( typearray, itemsschema.Schema(typestring), description参会人员名单 ), action_items: schema.Schema( typearray, itemsschema.Schema(typestring), description会议产生的行动项列表 ), }, required[title, date, participants, action_items] ) extraction_skill Skill( namemeeting_extractor, description从用户的会议描述中提取结构化会议要素, input_schemaMEETING_SCHEMA, )第二步创建周报总结 SkillFew-shot 引导# skills/summary_skill.py from google.adk import Skill WEEKLY_REPORT_EXAMPLES [ { input: {项目进度: 60%, 风险: 接口延迟高}, output: 核心功能完成大半当前主要瓶颈在接口性能建议优先排查第三方依赖耗时。, }, { input: {项目进度: 90%, 风险: 无}, output: 项目已近收尾整体推进顺利剩余工作集中在验收测试环节。, }, ] summary_skill Skill( nameweekly_summarizer, description根据会议记录生成周报摘要段落风格简洁、结果导向, examplesWEEKLY_REPORT_EXAMPLES, output_format不超过三句话概括核心进展和风险, )第三步创建数据库写入 SkillFunction Call 包装# skills/database_skill.py import sqlite3, datetime from google.adk import Skill DB_PATH data/meetings.db def init_db(): conn sqlite3.connect(DB_PATH) conn.execute( CREATE TABLE IF NOT EXISTS meetings ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT, meeting_date TEXT, participants TEXT, action_items TEXT, created_at TEXT ) ) conn.commit() conn.close() def insert_meeting(title: str, meeting_date: str, participants: list, action_items: list) - str: 把会议信息写入数据库返回插入成功的会议ID conn sqlite3.connect(DB_PATH) cur conn.execute( INSERT INTO meetings (title, meeting_date, participants, action_items, created_at) VALUES (?, ?, ?, ?, ?), (title, meeting_date, ,.join(participants), \n.join(action_items), datetime.datetime.now().isoformat()) ) conn.commit() conn.close() return f会议已保存ID: {cur.lastrowid} database_skill Skill( namemeeting_db, description将会议记录保存到本地数据库, tools[init_db, insert_meeting], )第四步创建周报流程 Skill顺序工作流# skills/weekly_flow.py from google.adk import Skill, Tool def fetch_all_meetings_from_db() - str: 查询数据库里本周的所有会议原始记录返回文本列表 conn sqlite3.connect(DB_PATH) rows conn.execute(SELECT title, action_items FROM meetings WHERE meeting_date date(now, -7 days)).fetchall() conn.close() return \n.join([f{title}: {items} for title, items in rows]) monthly_review_skill Skill( nameweekly_report_flow, description生成周报先从数据库读取本周会议再交总结模块生成周报文本, tools[ Tool.from_function(fetch_all_meetings_from_db), ], sub_skills[summary_skill], workflowsequential, )3.3 把 Skill 组装进 Agent 主程序# app.py from google.adk import Agent from skills.extraction_skill import extraction_skill from skills.database_skill import database_skill from skills.weekly_flow import weekly_report_flow agent Agent( namemeeting_assistant, description会议纪要与周报一体助手, instruction( 你是会议助理。收到用户描述会议信息的消息后 1. 先用会议抽取Skill整理成结构化数据 2. 再保存进数据库 3. 如果用户要求生成周报调用周报流程Skill汇总生成。 ), skills[extraction_skill, database_skill, weekly_report_flow], ) agent.run(请记录今天上午的例会主题是支付模块联调参会人有小A、小B讨论了两个行动项修复回调验签超时、补充异常监控告警。)3.4 实测效果与验证要点在真实环境跑完上面的流程后观察要点有三个。第一Agent 是否自动调用了meeting_extractor并把文案转成了结构化 JSON。如果它直接照抄原文很可能是 Schema 里字段描述不够明确或者“先抽取再保存”的顺序没有在 instruction 里写清楚。第二insert_meeting是否被触发且返回了 ID。如果 Agent 跳过了这个工具直接说“已记录”说明工具描述没有让模型感知到“必须落库”。第三生成周报时fetch_all_meetings_from_db是否先被调用、随后再生成摘要。如果顺序反了或者模型凭空生成内容需要把工作流改成workflowsequential并显式在工具描述里强调依赖关系。实测下来这套组合最常见的失败点不是代码本身而是指令表述不够显式。Agent 的 instruction 把“先做 A 再做 B 再做 C”写得越清楚流程就越稳定。这里的 instruction 字数不多但每一步的依赖和顺序都锁死了效果比单纯给模型一堆 Skill 要好得多。4. 常见问题与排查技巧实录Skill 开发过程中下面这些问题出现频率最高我把排查思路和解决方案整理成一份速查表。问题现象常见原因排查思路解决建议Skill 定义后Agent 从不触发它描述不清晰、与用户意图匹配度低检查该 Skill 的 description 是否包含用户会使用的关键词精简 description用动词开头覆盖常见问法模型调用 Skill 后输出格式混乱Schema 约束字段不严确认 required 字段完整enum 枚举值齐全增加描述样例必要时候用 JSON Schema 严格约束多个 Skill 功能重叠冲突边界模糊画出 Skill 决策树明确唯一入口将重叠的 Skill 合并或在 instruction 中加优先级模型跳过数据库写入直接答复用户工具描述未体现“必须执行”检查函数 docstring 里落库的意图在 instruction 中强调“所有会议记录必须落库后才能答复”顺序工作流里步骤颠倒流程约束不够硬尝试将流程显式定义为workflowsequential拆分更小粒度的 Tool用工具间数据依赖锁死顺序子 Agent 路由错误关键词匹配规则太简单检查dispatch_function的分词逻辑是否覆盖同义表述增加同义词映射或交给主 Agent 做意图判断4.1 排查技巧一单 Skill 隔离测试遇到问题最有效的办法是单独测试 Skill不要放在完整 Agent 里测。可以单独初始化一个只挂载一个 Skill 的临时 Agent输入一条精简指令看行为是否符合预期。这样可以排除多个 Skill 互相干扰的因素。全部通过后再组装回主 Agent。4.2 排查技巧二日志追踪 Skill 调用链ADK 的运行日志会记录模型是否发起了 Skill 调用、传入了什么参数、返回值是什么。在排查时不要只看最终输出要沿日志追踪完整链路。重点看四件事模型选用了哪个 Skill、参数是否合理、返回值是否被后续步骤消费、是否发生了重复调用。日志里如果模型在连续多轮里反复调用同一个只读工具通常意味着没有把结果缓存下来或者在提示词里缺少“拿到的信息够用就停止调用”的约束。4.3 排查技巧三注意 Tool 与 Skill 的边界认知很多人混淆这两个概念。Tool 是 Skill 内部的可执行单元Skill 则是面向 Agent 的能力入口。Agent 感知的是 Skill 的对外描述不直接感知 Tool 的具体实现。在设计阶段对外描述要稳定内部实现要灵活。这样后续替换 Tool 实现时对外接口不变Agent 行为就不会受影响。我自己在真实项目中曾为了图方便直接给 Agent 挂了一堆裸露的 Tool结果系统提示词越写越长模型经常搞不清该用哪个。后来统一把 Tool 分组收敛进 Skill把系统提示词精简成因情境触发的短指令整个 Agent 的判断准确率明显上升。一个额外好处是Skill 可以在不同项目之间直接复制新项目里只需要挂载同一套 Skill能力就整体迁移过来了。4.4 排查技巧四文档字符串要“面向模型编写”最后提醒一个非常容易被忽略的细节。代码里的函数 docstring 和 Skill 的 description真正的读者不是程序员而是大模型。面向模型写描述要包含三要素功能范围、触发条件、典型参数。不建议使用“可能会”这类模糊词。实测中描述精确到“输入为门店编号、输出为该门店当日订单数”比泛泛写“查询门店数据”的触发准确率高出一大截。如果希望行为更稳直接把参数名也写成自解释风格。比如把name写成shop_id_or_name模型就能理解这个字段的语义自动把用户问题里的门店名称填入。5. 写在最后的个人体会Skill 设计模式真正帮我解决的问题是让 Agent 项目不再是一次性的“提示词工程”而是一个可以持续迭代的软件工程。五种模式的边界不是死的同一个项目里完全可以混用。比如工作流模式内部套一个 Schema 约束模式子 Agent 内部再用 Function Call 包装模式——这种复合用法在真实业务里非常常见。一个建议从项目的第一天起就为每个 Skill 建立独立目录、独立描述、独立测试用例不要等代码膨胀到没法收拾再重构。Skill 命名和描述哪怕多花半小时推敲之后省下来的调试时间会远远超过这一点投入。我自己在写这一套代码的时候最大的感触是“Skill 的粒度”需要反复拿捏。太粗Agent 调用起来大而全浪费算力还容易误伤太细Agent 需要多次调用才能完成任务容易在参数传递中出错。一个比较实用的参考尺度是一个 Skill 对应一个可以独立描述且独立验收的业务能力点不要按“功能模块”划分更不要按“代码文件”划分。按这个尺度拿捏后续扩展时你会发现整个结构始终是清爽的。如果你最近也在用 ADK 做 Agent 开发可以先从第二个模式Function Call 包装入手其他四种等你遇到相应复杂度时再逐个引入。
