> ## 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 能力

> 在 AI 模型推理、Agent Skills、直接 API、带认证的写操作、MCP、A2A 发现和程序化支付之间做选择。

根据应用需要多少编排能力、控制力以及对外部副作用的处理，来选择接口。

## AI 模型推理

当主要任务是语言、推理、编程、视觉、图像生成或其他受支持的模型能力时，使用模型推理。

* Base URL：`https://api.aisa.one/v1`
* 从[模型](/docs/zh/guides/models)和 [Chat Completions API](/docs/zh/api-reference/chat/post_chat-completions) 开始。
* 使用实时目录或模型指南中的精确模型 ID。

如果工作流不需要外部数据或工具，通常只用模型推理就够了。

## Agent Skills

当用户需要的是一个完整的、面向任务的结果时，使用 Agent Skill。Skill 可以封装工具选择、工作流步骤、安全注意事项和输出结构。

* 从 [Agent Skills](/docs/zh/agent-skills) 和 [Skills 快速上手](/docs/zh/agent-skills/quickstart)开始。
* 如果已有 Skill 覆盖该任务，优先使用它。
* 当工作流依赖内部系统或组织特定规则时，创建自定义 Skill。

决策过程参见[预置 Skill 与自定义 Skill](/docs/zh/guides/learn/agent-skills-vs-tools)。

如需直接对比可复用工作流和由应用自己掌控的编排，参见 [Agent Skills 与直接 API](/docs/zh/concepts/agent-skills-vs-direct-apis)。

## 直接 API

当应用需要自己选择 endpoint、编排调用顺序、控制重试或数据处理时，使用直接 API。

* Base URL：`https://api.aisa.one/apis/v1`
* 从 [API 参考](/docs/zh/api-reference)开始。
* 只加载任务需要的那些 endpoint 页面。

直接 API 比 Skills 提供更强的控制力，但需要写更多编排代码。

## 带认证的写操作

当 agent 必须在外部系统中发送、发布、创建、更新或删除信息时，使用带认证的写操作。

执行前：

1. 确认所需的 OAuth 连接或委托凭证。
2. 把读操作和写操作分开。
3. 需要确认时，向用户展示将要产生的副作用。
4. 使用可用范围最小的权限和 endpoint。

不要因为拥有读取数据的权限，就推断自己拥有执行写操作的权限。

## MCP

在需要标准化工具发现和调用的兼容 agent 客户端中使用 MCP。

* 查看 [MCP manifest](https://aisa.one/.well-known/mcp.json)。
* 连接前检查每个 server 条目的 `status`。
* MCP server 处于规划状态，并不代表对应的 HTTP API 不可用；请单独查阅已文档化的 API。

## A2A 发现

使用 [Agent Card](https://aisa.one/.well-known/agent-card.json) 来发现高层能力、认证元数据、标签和示例任务。

从发现到调用的完整流程参见 [Agent 发现](/docs/zh/guides/agent-discovery)。当需要精确的请求和响应 schema 时，请获取 OpenAPI 规范。

## 程序化支付

当 agent 需要在运行时为受支持的 API 或服务付费时，使用程序化支付能力。

启用自主支付流程前，先定义：

* 每次请求和每个任务的最大金额。
* 资金来源和结算方式。
* 是否需要用户确认。
* 如何处理重试、重复扣费和失败响应。
* 保留什么样的审计记录。

参见 [AIsa 钱包与支付](/docs/zh/guides/pricing/wallet)和[面向 agent 的机器支付](/docs/zh/concepts/machine-payments-for-agents)。

从选择到结算的完整工作流参见[自主 API 采购](/docs/zh/use-cases/autonomous-api-purchasing)。

## 快速选择

| 需求              | 推荐接口           |
| --------------- | -------------- |
| 仅推理或生成          | AI 模型推理        |
| 可复用的端到端任务       | Agent Skill    |
| 自定义 endpoint 编排 | 直接 API         |
| 外部写入或发布操作       | 带认证的写操作        |
| 标准化的客户端工具发现     | MCP            |
| 高层机器能力发现        | A2A Agent Card |
| 运行时购买受支持的能力     | 程序化支付          |

如果任务描述的是结果而不是接口，请从[按目标查找能力](/docs/zh/by-goal)开始。