核心概念
不管用哪种方式接入,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 的路由规则:
- 不知道用哪个工具:先推荐,再从结果里选一个执行。
- 已经知道工具名:直接查详情拿到参数 Schema,再执行。不必再走推荐。
- 想按类别浏览:浏览 → 详情 → 执行。浏览结果里没有参数 Schema,执行前要先查详情。
- 用户问余额、账户:直接查账户,不要走推荐。
- 必填参数要靠别的工具查出来:先调用那个工具。推荐和详情结果里的
associated_tools字段会提示依赖关系,比如"本工具可能依赖 t1 的输出作为输入"。 - 执行结果里带有平台旁白(
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>" }也可能是音频、文件链接等类型,以工具说明为准。耗时较长的工具会先返回任务号,见异步任务与文件。
