API 参考
基本约定
- Base URL:
https://agentearth.ai - 鉴权:每个请求都带请求头
X-Api-Key: <API Key>。Key 在 API Keys 页面创建。 Authorization: Bearer只接受插件市场连接器(OAuth)签发的令牌,用它传 API Key 会返回 401。- 请求和返回都是 JSON。成功时 HTTP 200、
error_no为0;失败时error_no为-1,原因在error_msg。 - 推荐、浏览、详情、查账户不收费,只有执行按次计费。
示例里的 Key 从环境变量读取:
export AGENTEARTH_API_KEY="<你的 API Key>"推荐工具
POST /agent-api/v1/tool/recommend按自然语言任务推荐工具。不确定该用哪个工具时,先调这个接口。
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
query |
string | 是 | 任务或问题的自然语言描述 |
limit |
int | 否 | 返回工具数量,范围 1–50,默认 5 |
curl --request POST \
--url 'https://agentearth.ai/agent-api/v1/tool/recommend' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{"query":"查询北京未来三天的天气","limit":3}'返回
{
"error_no": 0,
"error_msg": "",
"total": 1,
"tools": [
{
"tool_name": "…",
"tool_url": "https://agentearth.ai/agent-api/v1/tool/execute?recommend_id=…&tool_name=…",
"description": "…",
"when_to_use": "…",
"credit": "1.8 AE credits per record, based on actual returned records.",
"input_schema": { "type": "object", "properties": { } },
"associated_tools": "…"
}
]
}各字段的含义见核心概念。credit 是价格说明文字,不是统一的数字。
执行工具
POST /agent-api/v1/tool/execute?tool_name=<工具名>执行一个工具。地址优先用推荐或详情返回的 tool_url(原样使用,其中的 recommend_id 改动后会返回"工具不存在");已知工具名时也可以只带 tool_name。
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
params |
object | 视工具而定 | 按该工具的 input_schema 组织的参数 |
curl --request POST \
--url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_get_result' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{"params":{"task_id":"test"}}'返回
{
"error_no": 0,
"error_msg": "",
"result": [
{ "type": "text", "text": "{\"status\":\"not_found\",\"task_id\":\"test\"}" }
],
"platform_annotations": { }
}result:工具返回的内容数组,常见text、image(含mimeType和 Base64data)等类型。失败时为空数组。platform_annotations:平台旁白,可能包含platform_note(平台做了什么)和platform_suggestion(建议下一步怎么做),见核心概念。error_no为0不代表工具一定给出了想要的结果,要读result的内容判断。- 耗时较长的工具会先返回任务号,见异步任务与文件。
浏览工具
GET /agent-api/v1/tool/list分页浏览在线工具。
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
page |
int | 否 | 页码,从 1 开始,默认 1 |
page_size |
int | 否 | 每页数量,默认 20,最大 100 |
keyword |
string | 否 | 关键词,匹配工具名、描述和标签 |
sort |
string | 否 | 排序:name_asc(默认)、name_desc、price_asc、price_desc |
curl --url 'https://agentearth.ai/agent-api/v1/tool/list?page=1&page_size=20&keyword=weather' \
--header "X-Api-Key: $AGENTEARTH_API_KEY"返回:total(符合条件的总数)、page、page_size,以及 tools 列表。每个工具含 tool_name、tool_url、description、when_to_use、credit,不含 input_schema;执行前请先查详情。
工具详情
GET /agent-api/v1/tool/detail?tool_name=<工具名>按精确的工具名查询单个工具,返回格式与推荐相同,tools 里是这一个工具,含 input_schema。
curl --url 'https://agentearth.ai/agent-api/v1/tool/detail?tool_name=ae_get_result' \
--header "X-Api-Key: $AGENTEARTH_API_KEY"查账户
GET /agent-api/v1/tool/account查询当前 API Key 所属账户的信息和余额。不接受查询参数和请求体。
curl --url 'https://agentearth.ai/agent-api/v1/tool/account' \
--header "X-Api-Key: $AGENTEARTH_API_KEY"返回
| 字段 | 说明 |
|---|---|
user_id |
账户 ID |
user_name |
用户名 |
key_name |
当前 API Key 的名称(不是 Key 本身) |
credit |
账户余额,8 位小数的字符串,如 "128.50000000" |
MCP
MCP Server 地址是 https://agentearth.ai/mcp-server/,传输方式为 Streamable HTTP,请求头 X-Api-Key 鉴权。5 个接口对应 5 个 MCP 工具:
| MCP 工具 | 对应接口 | 参数 |
|---|---|---|
RecommendTools |
推荐工具 | query、limit |
ExecuteTool |
执行工具 | tool_url(原样使用推荐返回的)、params |
ListTools |
浏览工具 | page、page_size、keyword、sort |
GetToolDetail |
工具详情 | tool_name |
GetAccountOverview |
查账户 | 无 |
和 HTTP 的差别:
- API Key 在连接时校验。连接之后如果 Key 在 API Keys 页面被停用,后续调用返回 403(JSON-RPC 错误码
-32004),重新启用即可恢复,不需要重新连接或授权。 - 返回内容是 JSON 字符串,放在
result.content[].text,格式与 HTTP 相同。 - 业务失败时
result.isError为true,原因在content[].text。 - 平台旁白以
<platform_annotation source="AgentEarth">…</platform_annotation>文本块追加在内容末尾。
错误码
| HTTP | 含义 | 建议处理 |
|---|---|---|
| 400 | 参数格式错误;工具不存在或已下线;tool_url 不完整(缺 tool_name) |
核对参数;重新推荐或查详情拿到正确的 tool_url |
| 401 | API Key 无效或已过期;或用 Authorization: Bearer 传了 API Key |
检查 Key,改用 X-Api-Key |
| 402 | 余额不足 | 充值后重试 |
| 403 | Key 已停用;或账号已被封禁 | 停用的 Key 在 API Keys 页面重新启用;账号封禁请联系客服 |
| 404 | 账户不存在(查账户接口) | 检查 Key 是否属于当前账户 |
| 405 | 请求方法不对(推荐、执行要用 POST,其余用 GET) | 换成正确的方法 |
| 429 | 调用太频繁 | 稍后重试 |
| 500 | 平台内部错误 | 稍后重试 |
| 502 | 上游服务商暂时不稳定 | 稍后重试,或换一个同类工具 |
401、403 时返回的是纯文本错误说明,不是 JSON。其余错误返回 JSON,error_no 为 -1,原因在 error_msg。
限流
- 按每分钟调用次数限流,每个用户、每个 API Key 分别计数,任一超限都会被拒绝。
- 超限返回 HTTP 429,
error_msg为Request frequency is too high...。 - 具体次数由平台配置,可能调整。查询异步结果的
ae_get_result不计入限流。
