跳转到主要内容
AIsa 发布了多个机器可读的发现资源,让自主智能体无需人工介入即可发现、理解并调用 AIsa 的能力。本指南逐一介绍这些资源,解释集成流程,并提供 Python、TypeScript 和 Bash 的可运行代码示例。智能体遵循的规则(如何连接、验证、报价、批准支出和处理错误)只有一个来源:智能体设置指南(agent setup guide);本页只指向它。

发现端点

AIsa 通过以下公开 URL 支持智能体和文档发现。这些资源读取时无需身份认证。

智能体发现的工作方式

发现流程包含四个步骤:发现、连接、检查和调用。自主智能体先阅读智能体设置指南和智能体卡片,了解 AIsa 的能力;通过 MCP 连接;检查确切的工具契约;最后调用已报价的请求。使用 API Key 直接调用 HTTP 是无法使用 MCP 的代码的文档化回退方案(fallback)。
1

发现

智能体阅读智能体设置指南,并从 aisa.one 获取 /.well-known/agent-card.json。卡片中包含技能列表,每项技能都有 id、name、description、tags 和 examples。智能体使用这些元数据判断 AIsa 能否完成当前任务。
2

连接(MCP + OAuth,主要流程)

智能体把 https://mcp.aisa.one/mcp 添加为远程 MCP 服务器,并通过浏览器 OAuth 登录;无需粘贴任何 Key。没有浏览器的客户端改为在 MCP 配置中发送 Authorization: Bearer $AISA_API_KEY。然后用一次免费的受保护调用验证连接:account 操作(或 use 配合 {"operation_id": "account"})。工具列表或 401 不算。参见通过 MCP 连接。
3

检查

通过 MCP,search 返回候选工具的确切名称、参数 Schema 和标价,batch_get_schema(也以 get_details 提供)返回最多 20 个工具的完整契约。HTTP 回退方案则获取 /openapi.yaml:参数类型、必填字段、身份认证要求和声明的定价。
4

调用

通过 MCP,智能体先用 batch_quote 对确切的调用报价,再用 batch_use 执行,并遵循智能体设置指南中的支出规则(报价返回 auto_execute_eligible: true 时自动执行,否则用一条消息给出报价总额请求批准)。HTTP 回退方案把请求连同 Authorization: Bearer $AISA_API_KEY 发送到 api.aisa.one,并遵循更严格的直接 HTTP 规则;部分只读端点也接受机器支付而无需 Key。

A2A 智能体卡片

Google Agent-to-Agent(A2A)协议定义了智能体发布自身能力的标准格式。AIsa 的智能体卡片位于 well-known URL,用于描述平台、身份认证要求和完整技能目录。

获取智能体卡片

智能体卡片结构

顶层字段描述智能体身份、身份认证和能力:

技能对象

skills 数组中的每一项都描述一项能力:

可用技能

AIsa 当前通过智能体卡片发布 13 项技能。下表中的名称和标签与实际发现 Payload 保持一致:

OpenAI 插件清单

为了兼容实现原始 ChatGPT 插件协议的智能体框架,AIsa 还在 /.well-known/ai-plugin.json 发布 ai-plugin.json 清单。该文件遵循 OpenAI 插件 Schema v1,并引用同一份 OpenAPI 规范。
清单包含 description_for_model 字段,列出关键 API 端点,帮助基于 LLM 的智能体无需解析完整 OpenAPI 规范即可理解可用工具。

OpenAPI 3.1 规范

/openapi.yaml 上的合并版 OpenAPI 规范覆盖全部 111 多条 AIsa API 路径,并按 10 个类别组织。它是构造 API 请求的权威机器可读契约。

获取并解析规范

API 类别

规范将端点组织为以下标签组:

端到端集成示例(HTTP 回退方案)

能使用 MCP 的智能体按上文的连接、检查、调用步骤,使用 search、batch_get_schema、batch_quote 和 batch_use 工具即可。下面的 Python 示例是无法使用 MCP 的代码的 HTTP 回退方案:智能体发现 AIsa 的能力,识别 chat-completions 技能,并发起经过身份认证的 API 调用。发起付费调用前,请遵循智能体设置指南中的批准规则和直接 HTTP 规则。

身份认证

通过 MCP 连接的智能体使用浏览器 OAuth 认证,无需处理任何 Key;没有浏览器的客户端在 MCP 配置中设置 Authorization: Bearer $AISA_API_KEY。HTTP 回退方案对 api.aisa.one 的每个请求使用同一个 Bearer Token:
部分只读端点接受机器支付而无需 Key。GET /v1/models 成功只是传输层检查,不能证明已认证的业务访问。请用一次免费的受保护调用验证(MCP 的 account,CLI 的 aisa balance)。 从 AIsa Dashboard 生成 API Key。有关权限范围、轮换和安全存储的详细密钥管理指南,请参阅身份认证。
发现资源(agent-card.json、ai-plugin.json、openapi.yaml、/servers 和各 llms.txt 文件)可公开读取,无需身份认证;对 api.aisa.one 的 API 调用需要所选路由文档中记录的认证方式。

集成模式

模式 1:基于标签匹配技能

智能体可以使用 tags 数组将任务匹配到技能。对于需要在运行时动态选择能力的智能体,这是推荐方式。

模式 2:基于示例匹配意图

对于基于 LLM 的智能体,examples 字段提供自然语言查询,可用于和用户意图进行语义相似度匹配。

交互式浏览工具

AIsa 提供两个基于浏览器的工具,用于探索发现界面:
  • API Explorer:用于浏览、测试和集成全部 111 多个端点的交互式 Swagger UI,包含实时请求和响应示例。
  • 智能体发现:可视化技能浏览器,支持搜索和标签筛选,并提供集成代码示例。

CORS 支持

发现端点包含宽松的 CORS 响应头(Access-Control-Allow-Origin: *),因此基于浏览器的智能体和 Web 应用无需代理服务器即可直接获取数据。适用于:
  • /.well-known/agent-card.json
  • /.well-known/ai-plugin.json
  • /openapi.yaml

相关页面

身份认证

API Key 的生成、权限范围、轮换和安全存储。

Agent Skills

浏览并安装适用于 Claude Code、Cursor 和 OpenClaw 的可组合技能。

快速开始

几分钟内完成第一个经过身份认证的 API 请求。