Skip to main content
AIsa 发布了三个机器可读的发现端点,让自主智能体无需人工介入即可发现、理解并调用 AIsa 的能力。本指南逐一介绍这些端点,解释集成流程,并提供 Python、TypeScript 和 Bash 的可运行代码示例。

发现端点

AIsa 通过以下 well-known URL 支持智能体发现。这三个端点都可公开访问,读取时无需身份认证,并包含宽松的 CORS 响应头,因此基于浏览器的智能体可以直接获取数据。

智能体发现的工作方式

发现流程包含三个步骤:发现检查调用。自主智能体先获取智能体卡片,了解 AIsa 的能力;再选择相关技能;最后根据 OpenAPI 规范中的请求和响应 Schema 调用相应 API 端点。
1

发现

智能体从 aisa.one 获取 /.well-known/agent-card.json。响应中包含技能列表,每项技能都有 idnamedescriptiontagsexamples。智能体使用这些元数据判断 AIsa 能否完成当前任务。
2

检查

智能体识别出相关技能后,会获取 /openapi.yaml,取得对应 API 端点的完整请求和响应 Schema。OpenAPI 规范提供参数类型、必填字段、身份认证要求和示例 Payload。
3

调用

智能体使用 OpenAPI 规范中的 Schema 构造经过身份认证的 API 请求,将其发送到 api.aisa.one 并处理响应。所有端点都使用 AIsa API Key 的 Bearer Token 身份认证。

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 类别

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

端到端集成示例

下面的 Python 示例演示从发现到调用的完整流程。自主智能体会发现 AIsa 的能力,识别 chat-completions 技能,并发起经过身份认证的 API 调用。

身份认证

所有 AIsa API 端点都需要 Bearer Token 身份认证。请在每个请求的 Authorization 请求头中包含 AIsa API Key:
AIsa Dashboard 生成 API Key。有关权限范围、轮换和安全存储的详细密钥管理指南,请参阅身份认证
发现端点(agent-card.jsonai-plugin.jsonopenapi.yaml)可公开读取,无需身份认证;但对 api.aisa.one 的所有 API 调用都需要有效的 Bearer Token。

集成模式

模式 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 请求。