Skip to main content
Agent Skill 封装了面向任务的指令、工具选择、工作流步骤、安全注意事项和输出规范。直接 API 集成则让应用显式掌控 endpoint、参数、调用顺序、重试和状态。 两者可以使用相同的底层 AIsa 能力。选择的核心在于：由谁负责编排，以及这个工作流需要多高的复用度。

​
逐项对比

Skill 并不天然是一个托管服务或黑箱 agent。它是一个可移植的指令包，用于教会兼容的运行时如何用已文档化的能力完成某项任务。

​
什么时候用 Agent Skill

以下情况优先用 Skill：
  • 用户要的是一个结果，而不是某个具体 endpoint。
  • 该工作流会在多个项目或 agent 客户端中重复使用。
  • 工具选择和调用顺序需要遵循一致的方法。
  • 证据规则、安全检查和输出结构应该随工作流一起传递。
  • 已有 Skill 覆盖该任务，并且可以在使用前审阅。
从 Agent Skills 目录和 Skills 快速上手开始。

​
什么时候用直接 API

以下情况优先用直接 API：
  • 应用必须选择精确的 endpoint 和参数。
  • 请求时机、缓存、分页、重试或降级行为是产品特有的。
  • 数据必须归一化成内部 schema。
  • 工作流依赖专有业务规则或内部状态。
  • 每一次外部调用都必须在应用代码和可观测性中显式体现。
从 API 参考开始，只加载任务需要的 endpoint 页面。

​
在合适的时候结合使用

两种方式是互补的。Skill 可以定义流程，直接 API 提供其中的具体操作。 例如，一个研究类 Skill 可能会指示 agent：
  1. 澄清研究问题。
  2. 调用特定的搜索或数据 API。
  3. 保留来源 URL 和获取时间。
  4. 用模型做综合。
  5. 标注缺乏支撑的结论和缺失的证据。
Skill 负责可复用的方法，API 仍然定义精确的请求和响应。

​
读取、写入和支付的边界

无论用哪种接口，都仍然需要对操作分类：
  • 读取： 获取信息，不改变外部系统。
  • 写入： 创建、发送、发布、更新、删除、关注，或以其他方式改变外部状态。
  • 支付： 产生计费的运行时采购，或发起一笔资金交易。
Skill 中提到某个写入或支付操作，并不等于授权执行它。产生副作用之前：
  1. 确认已连接的身份和授权。
  2. 需要确认时，展示操作目标和预期效果。
  3. 使用范围最小的权限和操作。
  4. 避免无上限或含义不清的重试。
  5. 核验外部执行结果和用量记录。

​
决策清单

通过这些问题来选择接口：
  • 这个任务是可复用的结果，还是产品特定的集成？
  • 谁应该掌控 endpoint 的调用顺序和任务状态？
  • 应用是否需要精确的参数和重试控制？
  • 是否有多个 agent 客户端会复用同一套指令？
  • 其中是否包含写入或支付操作？
  • 这个工作流将如何测试、审查和更新？
如果任务是用期望结果描述的，从按目标查找能力开始；如果接口已经确定，继续阅读按接口查找能力。

​
相关内容