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 和 Base64 data)等类型。失败时为空数组。
  • 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 不计入限流。