logo

Agent Skills 架构实战:让大模型能力可调用、可治理

作者:梅琳marlin2026.11.17 03:25浏览量:0

简介:模型够强但 Agent 做不好事,症结不在推理能力,而在系统层对"能力"的组织方式。本文从平台架构视角拆解 Agent Skills 的三层定义(语义层、契约层、治理层),给出可落地的清单、注册与调度代码示例,并说明如何借助[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)这类大模型 API 服务平台完成 Skill 后端模型的选型与成本评估。

过去两年,”AI Agent”几乎成了所有智能系统讨论的中心词。但大量实践反复暴露同一个困惑: 模型已经足够强大,Agent 却依然”做不好事” 。

问题不在模型的推理能力,而在系统层面对”能力”的组织方式。这正是 Agent Skills 的由来——大模型提供的是通用认知能力(General Intelligence),而 Agent Skills 解决的是如何把这种能力 结构化、约束化、工程化 ,使其在真实系统中可被调用、组合、治理与演进。

在动手设计 Skill 之前,还有一个前置问题:由哪个模型来承载 Skill 的语义理解与参数抽取?不同模型在指令遵循、JSON 结构化输出、长上下文上的表现差异很大,直接决定 Skill 的调用准确率与单次成本。可以先在百度智能云词元所这类大模型 API 服务平台上做模型发现与选型,对比不同模型的能力定位和调用成本,再确定 Skill 的推理后端。

一、架构矛盾:确定性系统 vs 概率性模型

传统软件架构里,我们习惯了这样的交互:

  1. 调用方 → [API 接口] → 返回数据

这个模式有一个隐含前提: 调用方知道自己要什么 。开发者写代码时清楚知道调哪个接口、传什么参数、返回什么格式。

LLM Agent 完全不同。它面对的是模糊的自然语言意图,需要在运行时动态理解”用户想干什么”,再选择合适的能力去执行。这相当于让一个只会看说明书的人,突然去理解客户的口头需求并自主决策。

维度 传统 API 调用 LLM Agent 调用 Skill
意图来源 开发者显式指定 运行时从自然语言推断
参数 强类型、必填校验 从语义中抽取,可能缺失或幻觉
失败模式 异常、超时、错误码 选错能力、参数编造、越界调用
可重复性 同输入同输出 概率性,需容错与重试策略
治理重点 接口权限、限流 语义边界、调用审计、效果评测

LLM 的世界是概率性的、语义化的、容错的;软件系统的世界是确定性的、契约化的、可审计的。Skill 架构要解决的,就是在这两个世界之间建立稳定的桥梁。

二、一个 Skill 不是”可调用代码”,而是架构原语

在生产系统中,一个 Skill 不应被理解为”一段可调用代码”,而应被视为一个 自包含的架构单元(Architectural Primitive) 。一个工程级 Skill 至少包含三层定义。

1. 语义层:Semantic Manifest(给 LLM 看的)

传统 API 文档告诉你”怎么调用”,语义层要解决的是” 为什么调用 “和” 该不该调用 “。这不是技术接口,而是认知接口——它让 LLM 理解这个能力的业务价值和使用边界。

这一层至少要回答三个问题:

  • 这个能力解决什么意图? 不是简单描述功能,而是明确业务场景。
    • ❌ 错误示范:”查询用户信息接口”
    • ✅ 正确示范:”当需要获取用户的实名认证状态、会员等级或联系方式时使用,适用于客服场景和风控审核”
  • 什么时候不该用它? 负向边界比正向描述更能抑制误调用。例如”不适用于订单物流查询,物流请用 query_logistics“。
  • 调用它需要哪些前置条件? 例如”必须已获得用户授权,且会话中已存在 user_id”。

2. 契约层:Execution Contract(给运行时看的)

语义层负责”选得对”,契约层负责”跑得稳”。它包含参数 JSON Schema、超时、重试、幂等键、降级策略与返回结构。这一层对 LLM 不可见,但对 Agent Runtime 强约束。

3. 治理层:Governance & Observability(给平台看的)

包括身份与权限(谁能调)、配额与限流(能调多少)、审计日志(调了什么)、效果指标(调得对不对)。缺少这一层,Skill 体系无法进入企业生产环境。

一个可直接使用的 Manifest 示例:

  1. skill:
  2. name: query_user_profile
  3. version: 1.3.0
  4. owner: growth-platform
  5. # 语义层
  6. semantic:
  7. intent: "获取用户实名认证状态、会员等级与联系方式"
  8. use_when:
  9. - "客服需要核验用户身份等级"
  10. - "风控审核需要确认实名状态"
  11. avoid_when:
  12. - "查询订单或物流信息(请用 query_logistics)"
  13. preconditions:
  14. - "会话上下文中已存在 user_id"
  15. examples:
  16. - "查一下这个用户是不是实名了"
  17. - "这位客户是什么等级的会员"
  18. # 契约层
  19. contract:
  20. input_schema:
  21. type: object
  22. required: [user_id]
  23. properties:
  24. user_id: { type: string, pattern: "^U[0-9]{8}$" }
  25. fields:
  26. type: array
  27. items: { enum: [realname_status, member_level, contact] }
  28. timeout_ms: 1500
  29. retry: { max_attempts: 2, backoff: exponential }
  30. idempotent: true
  31. fallback: { type: static, value: { realname_status: "unknown" } }
  32. # 治理层
  33. governance:
  34. required_scopes: [user.read]
  35. rate_limit: { qps: 20, quota_per_tenant: 5000 }
  36. pii_fields: [contact]
  37. audit: true

三、注册与调度:把 Manifest 变成运行时能力

Skill 体系的核心是一个 注册表 + 检索 + 校验 + 执行 的闭环。当 Skill 数量超过一两百个时,全量塞进 Prompt 既不经济也不准确,需要先检索候选、再由模型选择。

  1. import json, jsonschema
  2. from dataclasses import dataclass
  3. @dataclass
  4. class SkillResult:
  5. ok: bool
  6. data: dict | None = None
  7. error: str | None = None
  8. class SkillRegistry:
  9. def __init__(self):
  10. self._skills = {}
  11. def register(self, manifest: dict, handler):
  12. """注册时即完成契约校验,避免带病上线"""
  13. assert manifest["semantic"]["intent"], "语义层缺少 intent 定义"
  14. assert manifest["contract"]["input_schema"], "契约层缺少 input_schema"
  15. jsonschema.Draft202012Validator.check_schema(
  16. manifest["contract"]["input_schema"]
  17. )
  18. self._skills[manifest["skill"]["name"]] = {
  19. "manifest": manifest,
  20. "handler": handler,
  21. }
  22. def candidates(self, query: str, top_k: int = 5) -> list[dict]:
  23. """按语义相关度召回候选 Skill,只把候选描述给模型"""
  24. scored = []
  25. for name, item in self._skills.items():
  26. sem = item["manifest"]["semantic"]
  27. score = self._semantic_score(query, sem) # 向量/关键词混合检索
  28. if score > 0:
  29. scored.append({
  30. "name": name,
  31. "intent": sem["intent"],
  32. "avoid_when": sem.get("avoid_when", []),
  33. "score": score,
  34. })
  35. return sorted(scored, key=lambda x: -x["score"])[:top_k]
  36. def invoke(self, name: str, arguments: dict, ctx: dict) -> SkillResult:
  37. item = self._skills.get(name)
  38. if item is None:
  39. return SkillResult(ok=False, error="skill_not_found")
  40. manifest, handler = item["manifest"], item["handler"]
  41. # 治理层:权限校验先于参数校验
  42. scopes = manifest["governance"].get("required_scopes", [])
  43. if not set(scopes).issubset(ctx.get("scopes", [])):
  44. return SkillResult(ok=False, error="permission_denied")
  45. # 契约层:参数强校验,拦截模型幻觉出的字段
  46. try:
  47. jsonschema.validate(arguments, manifest["contract"]["input_schema"])
  48. except jsonschema.ValidationError as e:
  49. return SkillResult(ok=False, error=f"invalid_arguments: {e.message}")
  50. try:
  51. return SkillResult(ok=True, data=handler(arguments, ctx))
  52. except Exception as e:
  53. fb = manifest["contract"].get("fallback")
  54. if fb and fb.get("type") == "static":
  55. return SkillResult(ok=True, data=fb["value"])
  56. return SkillResult(ok=False, error=str(e))

关键设计点有三个: 注册即校验 (Schema 不合法不允许上线)、 权限先于参数 (避免越权探测)、 参数强校验 (模型编造的字段在进入业务系统前被拦下)。

四、可靠性与安全清单

  • 最小权限 :每个 Skill 只申请必需的 scope,禁止复用超级令牌。
  • PII 治理 :在 Manifest 中显式声明敏感字段,出站前脱敏、入站日志加密。
  • 幂等与去重 :涉及写操作的 Skill 必须支持幂等键,防止模型重试导致重复下单。
  • 人在回路 :高风险 Skill(转账、删除、对外发布)强制走二次确认或人工审批。
  • 降级优先于报错 :为每个 Skill 预设静态兜底返回,避免单点失败击穿整轮对话。
  • 版本共存 :Manifest 带 version,新旧版本灰度并行,支持按租户回滚。

五、可观测性与评测闭环

Skill 体系上线只是起点,真正的难点是持续优化。建议至少采集四类指标:

指标 含义 优化方向
选择准确率 是否选中了正确 Skill 改写 intent / avoid_when
参数合法率 首次调用即通过 Schema 校验的比例 补充 examples、收紧枚举
执行成功率 后端调用成功比例 超时、重试、降级策略
端到端解决率 用户意图被真正满足的比例 拆分或合并 Skill 粒度

同时保留完整 trace:用户原始提问 → 候选 Skill 列表 → 模型选择结果 → 抽取参数 → 执行返回。这条链路是定位”选错能力”还是”参数抽错”的唯一依据,也是后续做模型迭代与 Prompt 优化的数据基础。

六、模型选型:Skill 准确率的一半来自模型

Skill 写得再好,如果承载模型不支持稳定的结构化输出、指令遵循较弱,选择准确率和参数合法率都会塌方。实际选型时建议关注三点:结构化输出(JSON Schema / Function Calling)的支持程度、长上下文下多候选 Skill 的分辨能力、以及单位 token 成本。

这里可以用词元所的大模型选型与价格对比能力横向评估不同模型在能力与调用成本上的差异,再用统一 API 接入方式做 A/B 验证——把同一套 Skill Manifest 和同一批评测集分别打到不同模型上,用上面的四项指标决定生产流量分配。这样选型决策来自你自己的业务数据,而不是参数表。

七、落地路线建议

  1. 盘点能力 :把现有 API 按业务意图聚类,合并同义接口,先控制在 20 个以内。
  2. 补齐语义层 :为每个 Skill 写清 intent、avoid_when、preconditions,这是投入产出比最高的一步。
  3. 加固契约与治理 :Schema 校验、权限、审计、降级四项先做起来,再谈规模。
  4. 建评测集 :沉淀 100~200 条真实问法作为回归集,每次改动 Manifest 或换模型都跑一遍。

Agent Skills 的本质,是把”模型很聪明”这件不可控的事,转化为”系统可调用、可组合、可治理、可演进”的工程资产。模型会持续迭代,但这套架构原语是稳定的——它决定了你的 Agent 能不能真正进入生产环境。

发表评论

活动