Agent设计准则解析:薄框架与厚技能落地指南
作者:渣渣辉2026.11.16 11:39浏览量:1简介:本文系统解析Agent设计准则“薄框架、厚技能”,说明框架与技能的分工、契约设计、落地步骤、适用边界与合规风险。读者可获得技能清单模板、调用契约示例与避坑方法,从而提升Agent的可维护性、可扩展性和迭代效率。
一、概念定义:什么是“Thin Harness, Fat Skills”
“Thin Harness, Fat Skills”可译为“薄框架、厚技能”,是Agent系统设计中的一条重要架构准则。其核心思路是:把Agent的通用执行外壳保持得尽量轻、稳定、可复用,把具体业务逻辑、领域知识、工具调用、流程策略等可变能力沉淀到可插拔的技能模块中。
其中,Harness通常指Agent的运行骨架与控制层,负责主循环、任务编排、上下文管理、工具调度、错误处理、重试策略与安全护栏等。它回答的问题是:“Agent如何组织一次完整的目标驱动执行?”
Skills则指Agent可以调用的具体能力单元,例如订单查询、数据清洗、报告生成、告警排查、工单创建、规则校验等。它回答的问题是:“Agent具体能把哪些事情做成?”
因此,这条准则可以概括为:框架负责“怎么跑”,技能负责“跑什么”。框架保持通用与稳定,技能承载业务能力并持续扩展,从而实现控制逻辑与业务能力的清晰解耦。
二、为什么需要这条准则?常见误区有哪些?
在Agent早期实践中,常见两类问题。
第一类是“胖框架”。开发者把业务规则、领域判断、特定流程写进主循环,导致框架越来越重。每新增一个场景,都要修改核心逻辑,回归成本变高,系统可维护性下降。
第二类是“瘦技能”。开发者把大量控制逻辑塞进技能函数,表面上灵活,实际会造成调度混乱、状态难以追踪、错误难以定位,最终让Agent行为不可控。
“薄框架、厚技能”的价值在于:
- 提升可维护性:框架保持稳定,业务变化集中在技能层。
- 增强可扩展性:新增能力可通过增加技能实现,减少框架重构。
- 降低迭代成本:技能可以独立开发、测试和替换。
- 强化可控性:权限校验、日志审计、错误处理可统一放在框架层。
- 改善可测试性:框架逻辑与技能逻辑可以分别验证。
三、核心组成:薄框架保留什么,技能层沉淀什么?
3.1 薄框架通常包含哪些通用能力
一个精简的Harness通常只保留跨场景稳定的控制职责:
- 执行循环:驱动“感知—规划—调用—观察—再决策”的闭环。
- 任务编排:管理子任务拆解、依赖关系与调用顺序。
- 上下文管理:维护对话历史、中间状态与记忆压缩策略。
- 工具调度:向技能发起调用、收集结果、处理超时与重试。
- 安全与护栏:通过统一权限校验降低越权风险,并配合最小权限与审计。
- 错误处理:统一异常捕获、降级策略、重试机制与人工转接。
框架的设计目标应是通用、稳定、可复用。它不需要知道某个技能内部如何实现,只需依据技能契约进行安全调度。
3.2 厚技能通常包含哪些业务能力
技能层是Agent业务能力的真正承载者,可以包括:
- 领域知识与规则库:行业术语、业务规则、合规约束。
- 专用工具集:查询、计算、写入、外部接口调用等原子能力。
- 操作流程与策略:特定场景下的分步处理逻辑。
- 数据校验与转换:对输入输出进行结构化校验与规范化。
- 提示与推理策略:针对特定任务优化的指令模板或推理方式。
3.3 技能清单模板
在建设技能层时,可以先使用统一清单描述每个技能:
| 技能名称 | 输入 | 输出 | 依赖 | 权限 | 失败降级 |
|---|---|---|---|---|---|
| query_order | 用户ID、订单ID | 订单状态、摘要 | 订单系统接口 | 只读用户订单 | 返回未知并请求确认 |
| create_ticket | 问题描述、优先级 | 工单编号 | 工单系统接口 | 创建工单 | 转人工 |
| clean_dataset | 原始数据表 | 清洗后数据表 | 数据处理工具 | 读原始表、写临时表 | 回滚并保留原数据 |
这个模板能提前明确技能边界,减少框架与技能之间的相互渗透。
四、工作原理:框架与技能如何协同
Agent运行过程可以抽象为:
用户目标输入│▼薄框架 Harness1. 解析目标与管理上下文2. 判断需要调用哪些技能3. 执行权限与安全校验4. 调用技能 A / B / C5. 观察结果并继续规划6. 超时、失败、重试或人工转接│ ▲▼ │厚技能层 Skills:技能A、技能B、技能C……
框架在循环中反复进行“规划—调用—观察”,具体执行委托给技能。技能之间彼此独立,通过框架统一编排;技能内部可以有复杂逻辑,但对外只暴露清晰契约。
4.1 技能契约示例
技能契约应至少包含输入、输出、超时、重试、错误码和失败降级策略。例如:
skill:name: query_order_statusinput:user_id: stringorder_id: stringoutput:status: stringorder_summary: objecttimeout_ms: 3000max_retries: 2retry_backoff_ms: 500error_codes:- INVALID_ORDER- PERMISSION_DENIED- UPSTREAM_TIMEOUTfailure_fallback: return_uncertain_status_and_ask_user
字段说明:
- input:明确技能需要的最小输入,避免无边界传参。
- output:明确返回结构,便于框架统一消费。
- timeout_ms:控制单次调用等待时间,防止任务卡死。
- max_retries与retry_backoff_ms:定义重试次数和退避间隔。
- error_codes:让错误可识别、可分类、可处理。
- failure_fallback:定义失败后的降级策略,例如返回不确定状态、请求用户确认或转人工。
通过契约化设计,框架不需要理解每个技能的内部实现,只需要根据契约完成调度与校验。
五、如何落地:从0到1采用薄框架厚技能
可以按以下步骤落地:
- 明确Agent边界:先确定目标、输入、输出与不可越权范围。
- 定义技能契约:先写输入输出、依赖、权限和失败策略。
- 搭建薄框架:实现基础执行循环、调度、日志和错误处理。
- 沉淀技能模块:每个技能独立实现、独立测试。
- 接入安全与审计:统一处理权限、日志、敏感操作确认。
- 建立观测体系:记录每次调用轨迹、耗时、错误码与结果。
- 持续迭代技能:根据效果数据优化提示、工具和流程。
落地检查表:
- 技能是否有清晰输入输出?
- 技能是否声明依赖与权限?
- 是否有超时、重试与失败降级?
- 日志是否脱敏并可审计?
- 技能是否可以脱离框架单独测试?
- 框架是否避免了业务硬编码?
六、典型应用场景与适用边界
以下场景适合采用“薄框架、厚技能”:
- 企业客服与售后Agent:框架处理会话与转接,技能覆盖订单查询、工单创建、规则解答等。
- 运维与告警处理Agent:框架管理诊断流程,技能封装检测、排查、修复动作。
- 数据分析Agent:框架负责任务编排,技能提供数据抽取、清洗、统计、可视化等能力。
- 多工具协同自动化:框架串接流程,技能封装具体业务操作。
但需要注意:简单单轮或线性流程不必强制采用,避免过度编排。如果任务输入输出固定、状态少、无需多工具协同或自主重规划,使用简单工作流或函数调用即可。
七、相关概念辨析:与哪些设计容易混淆?
7.1 与胖框架的区别
胖框架把业务逻辑写进控制层,导致框架随业务膨胀;薄框架则只保留通用控制,业务能力下沉到技能层。
7.2 与单一大提示词的区别
把所有逻辑塞进一个大提示词看似简单,但会降低模块化和可维护性。厚技能强调能力单元化、契约化,更便于独立演进。
7.3 与微服务的类比
二者思想相通:职责分离、边界清晰、模块可独立替换。技能之于框架,类似服务之于网关。
agent-">7.4 与单Agent工作流、函数调用链的区别
单Agent工作流适合流程较固定、节点较清晰的场景;函数调用链适合少量函数顺序调用。若流程线性、状态简单、无需复杂编排与统一护栏,不必强行拆分为厚技能体系。何时不采用?当系统处于验证期、任务简单、调用链短且扩展预期较低时,优先使用轻量方案。
八、风险与注意事项:如何避免踩坑?
8.1 如何避免越权风险?
权限校验应集中在框架层,避免分散到各技能。应采用最小权限原则,对高风险操作增加确认、审计与留痕机制。
8.2 如何保障数据隐私与合规?
技能调用应遵循数据最小化、日志脱敏、隐私合规与审计留痕。仅收集完成任务所需的最小数据,敏感字段在日志中脱敏,并按合规要求保存和销毁记录。
8.3 如何防止上下文膨胀?
技能增多后,上下文容易膨胀。框架应支持摘要压缩、裁剪策略、检索增强、分块管理和会话清理。
8.4 如何避免过度拆分?
技能粒度过细会增加调度复杂度。应在“独立演进”和“调用成本”之间取得平衡。高频强关联能力可合并,低频独立能力再拆分。
8.5 如何独立测试与观测?
技能应能脱离框架单独测试,框架逻辑则通过统一调度链路验证。每次技能调用应记录日志与轨迹,便于排错和效果评估。
九、常见问题与排错思路
9.1 技能越多越好吗?
不是。技能数量应服务于场景需求。过多技能会增加选择、调度和上下文管理成本。
9.2 框架需要了解技能内部实现吗?
通常不需要。框架应依赖契约,而非内部实现。这样可以降低耦合,提升替换效率。
9.3 调用失败应如何处理?
先根据错误码分类:输入错误应返回明确提示;权限错误应拒绝或升级;上游超时可重试或降级;未知错误应转人工或记录异常。
9.4 如何判断架构是否过度设计?
如果系统只是单轮问答、固定顺序调用、无复杂状态管理,却仍引入大量技能编排和复杂护栏,就可能过度设计。
十、总结
“Thin Harness, Fat Skills”的本质,是通过薄框架承载通用控制,通过厚技能承载业务能力,实现Agent系统的清晰解耦。框架保持稳定、安全、可复用,负责调度、状态、上下文与错误处理;技能层保持丰富、专业、可插拔,承载真实业务复杂度。
采用这一准则,可以帮助开发者建立清晰的架构边界,提升可维护性、可扩展性与迭代效率。但其适用前提是系统具有持续扩展能力,并需要控制自主执行风险。对于简单任务,应选择更轻量的工作流或函数调用方案,避免过度编排。

登录后可评论,请前往 登录 或 注册