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

# AIsa 架构与集成边界

> 理解 AIsa 在 agent 应用与上游模型、API、Skills、写操作和计费系统之间所处的位置。

AIsa 位于 agent 应用和受支持的上游能力之间。应用向 AIsa endpoint 发送带认证的请求；AIsa 把请求路由到相应的模型或 API 集成，并返回结果。

## 高层请求路径

```text theme={null}
Agent 或应用
  -> AIsa 模型或 API endpoint
  -> 选定的上游能力
  -> AIsa 响应和用量记录
  -> 应用侧校验和状态处理
```

Agent Skills 和机器发现资源可以帮助 agent 选择和理解能力，但它们不会取代运行时的请求路径。

## Endpoint 家族

| 入口        | Base URL                       | 职责                      |
| --------- | ------------------------------ | ----------------------- |
| 模型推理      | `https://api.aisa.one/v1`      | 模型请求和兼容的推理路由            |
| 数据与能力 API | `https://api.aisa.one/apis/v1` | 搜索、金融、社交、公司、媒体等受支持的 API |
| 文档与发现     | `https://aisa.one`             | 面向人和机器的能力元数据            |

最小集成路径参见 [Agent 快速上手](/docs/zh/agent-quickstart)。

## AIsa 负责什么

取决于所选入口，AIsa 可能负责：

* 在 AIsa 边界上的统一认证。
* 路由到受支持的模型或 API 提供商。
* 归一化或已文档化的 endpoint 契约。
* 用量核算和计费。
* 机器可读的能力元数据。
* 面向 agent 运行时的可复用 Skill 指令。

## 应用仍然要负责什么

应用仍然要负责：

* 用户意图和授权。
* 业务逻辑和任务状态。
* 证据标准和结果校验。
* 客户端环境中的密钥存储。
* 与操作类型相匹配的重试和幂等策略。
* 外部写入和支付的确认流程。
* 应用数据的长期存储。
* 能力不可用时的降级行为。

统一网关并不能免除应用自身的策略。

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

在执行前对每个操作分类：

1. **读取：** 获取数据，不改变外部系统。
2. **写入：** 创建、更新、发送、发布或删除外部数据。
3. **支付：** 转移价值，或授权一次计费的运行时采购。

不要假设允许某一类操作的凭证同样允许另一类。对写入和支付要采用更严格的确认和重试策略。

## 数据与提供商边界

AIsa 与上游提供商集成。为完成某个操作所需的请求可能会发送给选定的提供商。请结合具体业务查阅[安全](/docs/zh/guides/security)以及相关的上游条款。

关于最新的模型和 API 契约，请以实时或自动生成的来源为准，而不是架构说明文字：

* [模型](/docs/zh/guides/models)
* [API 参考](/docs/zh/api-reference)
* [OpenAPI 规范](https://aisa.one/openapi.yaml)

## 部署注意事项

投入生产前，请定义：

* 健康检查和超时预期。
* 读取与写入分别采用的重试策略。
* 预算和余额监控。
* 提供商或路由的降级策略。
* 排除密钥和敏感请求内容的日志方案。
* 报告成功之前的校验步骤。

整体匹配度评估参见[何时使用 AIsa](/docs/zh/evaluate/when-to-use-aisa)。