核心概念

不管用哪种方式接入,Agent 能做的都是同样五个动作。理解这五个动作和调用顺序,Agent 就能少走弯路、少花积分。

五个动作

动作 HTTP 接口 MCP 工具 CLI 说明 收费
推荐工具 POST /agent-api/v1/tool/recommend RecommendTools ae recommend 用自然语言描述任务,返回候选工具、参数 Schema 和价格说明 免费
执行工具 POST /agent-api/v1/tool/execute ExecuteTool ae execute 传入参数执行工具,返回结果 按次计费
浏览工具 GET /agent-api/v1/tool/list ListTools ae list 分页、按关键词浏览在线工具;不返回参数 Schema 免费
工具详情 GET /agent-api/v1/tool/detail GetToolDetail ae detail 按精确的工具名查询,含参数 Schema 免费
查账户 GET /agent-api/v1/tool/account GetAccountOverview ae account 当前用户、Key 名称、余额 免费

只有执行工具会扣积分,调用失败不扣费。详见计费与积分。

调用顺序

给 Agent 的路由规则:

  1. 不知道用哪个工具:先推荐,再从结果里选一个执行。
  2. 已经知道工具名:直接查详情拿到参数 Schema,再执行。不必再走推荐。
  3. 想按类别浏览:浏览 → 详情 → 执行。浏览结果里没有参数 Schema,执行前要先查详情。
  4. 用户问余额、账户:直接查账户,不要走推荐。
  5. 必填参数要靠别的工具查出来:先调用那个工具。推荐和详情结果里的 associated_tools 字段会提示依赖关系,比如"本工具可能依赖 t1 的输出作为输入"。
  6. 执行结果里带有平台旁白(platform_annotations):先按旁白的提示处理,见下文。

推荐结果里有什么

推荐接口按匹配程度返回一组工具,每个工具包含:

字段 说明
tool_name 工具名,全局唯一
tool_url 执行这个工具的完整地址,原样使用
description 工具能做什么
when_to_use 什么情况下该用它
input_schema 参数的 JSON Schema
credit 价格说明,是一段文字,如"每次调用 1 积分"、"按实际返回记录数计费"
associated_tools 依赖或配合使用的其他工具(可能为空)

Agent 根据 description 和 when_to_use 判断哪个工具最合适,再按 input_schema 组织参数。

tool_url 要原样使用

推荐返回的 tool_url 类似:

https://agentearth.ai/agent-api/v1/tool/execute?recommend_id=…&tool_name=…

其中的 recommend_id 是本次推荐的凭证,改动 tool_url 里的任何字符都会导致"工具不存在"。执行时直接把它传给执行接口(MCP 下传给 ExecuteTool 的 tool_url 参数),不要自己拼接或改写。

不经过推荐、已经知道工具名时,也可以直接执行:

https://agentearth.ai/agent-api/v1/tool/execute?tool_name=<工具名>

平台旁白

执行结果里可能带有 platform_annotations,这是 AgentEarth 给 Agent 的补充说明,常见两种:

  • platform_note:平台做了什么。比如"提交前修正了你的参数:缺少 destination,已补为 …"。
  • platform_suggestion:建议下一步怎么做。比如换一个更合适的工具、调整参数。

MCP 下,旁白以 <platform_annotation source="AgentEarth">…</platform_annotation> 文本块的形式追加在结果末尾。Agent 应该先读旁白,再决定是直接使用结果还是按建议重试。

怎样判断调用成功

接入方式 成功 失败
HTTP error_no 为 0 error_no 为 -1,原因在 error_msg;HTTP 状态码见 API 参考
MCP isError 不为 true isError 为 true,原因在 content[].text
CLI 退出码为 0 退出码非 0,返回的 JSON 里有错误说明

注意:error_no 为 0 只代表平台把请求成功交给了工具,不等于工具一定给出了想要的结果。比如参数校验没通过、上游没有查到数据时,也可能返回 HTTP 200、error_no 为 0,说明写在 result 的文本内容里。Agent 要读结果内容判断,不能只看 error_no。

结果的格式

执行接口的 result 是一个数组,每一项是工具返回的一段内容,常见的有:

{ "type": "text", "text": "{\"status\":\"1\",\"results\":[...]}" }
{ "type": "image", "mimeType": "image/png", "data": "<Base64>" }

也可能是音频、文件链接等类型,以工具说明为准。耗时较长的工具会先返回任务号,见异步任务与文件。