发现端点
AIsa 通过以下 well-known URL 支持智能体发现。这三个端点都可公开访问,读取时无需身份认证,并包含宽松的 CORS 响应头,因此基于浏览器的智能体可以直接获取数据。智能体发现的工作方式
发现流程包含三个步骤:发现、检查和调用。自主智能体先获取智能体卡片,了解 AIsa 的能力;再选择相关技能;最后根据 OpenAPI 规范中的请求和响应 Schema 调用相应 API 端点。1
发现
智能体从
aisa.one 获取 /.well-known/agent-card.json。响应中包含技能列表,每项技能都有 id、name、description、tags 和 examples。智能体使用这些元数据判断 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:
集成模式
模式 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 请求。