> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Skills 与直接 API

> 判断 agent 应该沿用可复用的 AIsa Skill，还是由应用自己编排、直接调用各个 API。

**Agent Skill** 封装了面向任务的指令、工具选择、工作流步骤、安全注意事项和输出规范。**直接 API 集成**则让应用显式掌控 endpoint、参数、调用顺序、重试和状态。

两者可以使用相同的底层 AIsa 能力。选择的核心在于：由谁负责编排，以及这个工作流需要多高的复用度。

## 逐项对比

| 需求            | Agent Skill         | 直接 API                  |
| ------------- | ------------------- | ----------------------- |
| 基本单位          | 完整任务或工作流            | 单个 endpoint 操作          |
| 编排            | 写入可复用的指令和配套文件       | 由应用实现                   |
| 参数控制          | 由 Skill 引导          | 完全由应用控制                 |
| 跨 agent 客户端复用 | 客户端支持 Skill 格式时复用度高 | 需要共享应用代码或 SDK 封装        |
| 可审查性          | 查看 Skill 指令和引用的工具   | 查看源码、API 调用和 schema     |
| 自定义业务状态       | 通常由运行时或应用提供         | 完全由应用控制                 |
| 维护            | 工作流变化时更新 Skill      | 契约或逻辑变化时更新集成代码          |
| 最适合           | 流程已知、可重复的结果         | 产品特定的编排或精细的 endpoint 控制 |

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

## 什么时候用 Agent Skill

以下情况优先用 Skill：

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

从 [Agent Skills 目录](/docs/zh/agent-skills)和 [Skills 快速上手](/docs/zh/agent-skills/quickstart)开始。

## 什么时候用直接 API

以下情况优先用直接 API：

* 应用必须选择精确的 endpoint 和参数。
* 请求时机、缓存、分页、重试或降级行为是产品特有的。
* 数据必须归一化成内部 schema。
* 工作流依赖专有业务规则或内部状态。
* 每一次外部调用都必须在应用代码和可观测性中显式体现。

从 [API 参考](/docs/zh/api-reference)开始，只加载任务需要的 endpoint 页面。

## 在合适的时候结合使用

两种方式是互补的。Skill 可以定义流程，直接 API 提供其中的具体操作。

例如，一个研究类 Skill 可能会指示 agent：

1. 澄清研究问题。
2. 调用特定的搜索或数据 API。
3. 保留来源 URL 和获取时间。
4. 用模型做综合。
5. 标注缺乏支撑的结论和缺失的证据。

Skill 负责可复用的方法，API 仍然定义精确的请求和响应。

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

无论用哪种接口，都仍然需要对操作分类：

* **读取：** 获取信息，不改变外部系统。
* **写入：** 创建、发送、发布、更新、删除、关注，或以其他方式改变外部状态。
* **支付：** 产生计费的运行时采购，或发起一笔资金交易。

Skill 中提到某个写入或支付操作，并不等于授权执行它。产生副作用之前：

1. 确认已连接的身份和授权。
2. 需要确认时，展示操作目标和预期效果。
3. 使用范围最小的权限和操作。
4. 避免无上限或含义不清的重试。
5. 核验外部执行结果和用量记录。

## 决策清单

通过这些问题来选择接口：

* 这个任务是可复用的结果，还是产品特定的集成？
* 谁应该掌控 endpoint 的调用顺序和任务状态？
* 应用是否需要精确的参数和重试控制？
* 是否有多个 agent 客户端会复用同一套指令？
* 其中是否包含写入或支付操作？
* 这个工作流将如何测试、审查和更新？

如果任务是用期望结果描述的，从[按目标查找能力](/docs/zh/by-goal)开始；如果接口已经确定，继续阅读[按接口查找能力](/docs/zh/by-interface)。

## 相关内容

* [用一套 API 打通模型、数据和 Agent 工具](/docs/zh/concepts/unified-model-data-tools-api)
* [预置 Skill 与自定义 Skill](/docs/zh/guides/learn/agent-skills-vs-tools)
* [AIsa 架构与集成边界](/docs/zh/evaluate/architecture)
* [安全评估指南](/docs/zh/evaluate/security)