> ## 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.

# 用一套 API 打通模型、数据和 Agent 工具

> 了解 AIsa 在模型、实时数据、Agent Skills、写操作、发现和计费上统一了什么，以及哪些部分仍然因能力而异。

AIsa 为 AI agent 提供了一个统一的资源和交易边界，覆盖受支持的模型、API、数据服务、Agent Skills 和付费能力。这样可以减少应用需要管理的提供商账号、凭证、发现格式和计费关系数量。

"统一"**并不**意味着所有能力都使用完全相同的 endpoint、请求 schema、计价单位或授权方式。它意味着 agent 可以从同一个产品和账号边界出发，找到合适的入口，然后使用该能力对应的精确契约。

## AIsa 统一了什么

对于受支持的能力，AIsa 可以为下列环节提供共同起点：

* **产品发现：** 判断任务需要的是模型、Skill、直接 API、带认证的写操作还是支付流程。
* **账号访问：** 用一个 AIsa 账号和 API 凭证访问已文档化的模型与 API。
* **机器发现：** 查看 Agent Card、MCP manifest、OpenAPI 规范和 llms 资源。
* **用量可见性：** 通过 AIsa 的用量和账单页面查看计费的模型与 API 消耗。
* **技术路由：** 从任务目标出发，直达相关性最高的最小文档和 API 契约。

带认证的写操作可能还需要提供商特定的 OAuth 连接或委托凭证。仅拥有 AIsa API 密钥本身，并不等于获得了对外部系统写入的授权。

## 哪些部分仍然因能力而异

每种资源都可能有自己的运行契约：

| 关注点                 | 为什么会有差异                          |
| ------------------- | -------------------------------- |
| Endpoint 和请求 schema | 模型推理、搜索、金融数据和社交 API 接受的输入不同      |
| 响应语义                | 生成文本、来源记录、市场数据和操作回执需要不同的校验方式     |
| 计费单位                | 用量可能按 token、请求次数、媒体产出或其他已说明的单位计量 |
| 可用性和速率限制            | 不同能力可能依赖不同的上游提供商和配额              |
| 额外授权                | 写操作可能需要 OAuth、账号连接或用户显式确认        |
| 重试行为                | 读取的重试方式往往与写入或付费请求不同              |

请以 [OpenAPI 规范](https://aisa.one/openapi.yaml)和具体文档页面作为实现依据。

## 资源类型

| 资源          | 何时使用                  | 从哪里开始                                                         |
| ----------- | --------------------- | ------------------------------------------------------------- |
| AI 模型推理     | 任务是推理、生成、编程、视觉或媒体处理   | [模型](/docs/zh/guides/models)                                       |
| 实时数据或专用 API | 工作流需要实时、结构化、由提供商支撑的信息 | [API 参考](/docs/zh/api-reference)                                   |
| Agent Skill | 结果可复用，且适合沿用成熟工作流      | [Agent Skills](/docs/zh/agent-skills)                              |
| 带认证的写操作     | agent 必须改变外部系统        | [按接口查找能力](/docs/zh/by-interface#带认证的写操作)                           |
| 机器发现        | 客户端需要以程序方式查看能力和契约     | [Agent 发现](/docs/zh/guides/agent-discovery)                        |
| 程序化支付       | 需要在明确控制下于运行时购买受支持的能力  | [面向 AI agent 的机器支付](/docs/zh/concepts/machine-payments-for-agents) |

## 示例：先研究，再执行经审批的操作

一个任务可以跨越多个入口，但不应把它们当作可互换的：

1. 用[按目标查找能力](/docs/zh/by-goal)选择研究路径。
2. 调用搜索或数据 API 获取实时证据。
3. 用模型对证据做比较和综合。
4. 如果结果需要发布或发送，把这一步归类为带认证的写操作。
5. 确认已连接的身份，并在需要时请求确认。
6. 分别检查用量和外部执行结果。

统一的边界减少了集成碎片化。任务状态、证据标准、授权策略、重试逻辑和结果校验仍然由应用自己负责。

## 什么时候统一接口更有用

在以下情况可以考虑这种架构：

* agent 既需要模型，也需要实时外部数据。
* 否则产品就得维护多个提供商集成。
* 多个 agent 客户端需要复用同一批 Skills 或发现资源。
* 工作流需要跨不同能力类型的统一用量视图。
* 希望增量接入新资源，而不必重新设计整个 agent。

## 什么时候直接对接更简单

在以下情况直接对接提供商可能更好：

* 一个稳定的模型或 API 就能完成全部任务。
* 团队需要 AIsa 未开放的提供商特有功能。
* 现有的可靠性、合规、采购和计费流程已经覆盖了该提供商。
* 不希望引入额外的路由或计费依赖。

AIsa 不是非此即彼的架构。先从最小可用的入口开始，只有当工作流确实需要时，再引入其他资源类型。

## 下一步

* [Agent Skills 与直接 API](/docs/zh/concepts/agent-skills-vs-direct-apis)
* [模型网关与 Agent 能力层](/docs/zh/concepts/model-gateway-vs-capability-layer)
* [AIsa 架构与集成边界](/docs/zh/evaluate/architecture)
* [何时使用 AIsa](/docs/zh/evaluate/when-to-use-aisa)
* [按接口查找能力](/docs/zh/by-interface)