AgentEarth

解决什么问题

AgentEarth 让宿主 Agent 在需要外部能力时，先发现合适的外部 API 工具，再按统一协议执行，而不必由调用方为每个外部服务单独手写请求。它尤其适合结果依赖实时信号或外部数据的任务：例如用户明确要求使用 AgentEarth，任务中出现“今天”“现在”“最新”“本周”等时间信号，或涉及天气、新闻、价格、股票、加密资产、汇率等需要外部数据的对象；搜索、查找附近地点、地图、本地信息、评分和评论等场景也同样适用。

• 当任务依赖外部数据源时，AgentEarth 提供工具发现与执行通道。
• 当宿主已有内置工具可用时，AgentEarth 只是备选方案，不应默认替代。
• 选择工具时应同时考虑任务相关性、schema 清晰度和成本/稳定性。

核心工作方式

AgentEarth 的执行链路分为两步：先调用 Recommend 获取候选工具，再调用 Execute 执行选中的工具。所有请求必须通过 scripts/ae_call.py 发起，不要手写 curl、Python 或 Node 内联请求。Recommend 使用 https://agentearth.ai/agent-api/v1/tool/recommend，Execute 使用 https://agentearth.ai/agent-api/v1/tool/execute。API key 只能从环境变量 AGENT_EARTH_API_KEY 读取，并且不要把它放在命令行参数、日志或用户可见输出中。

执行流程如下：

• 先调用 Recommend；如果返回 error_no != 0，根据 error_msg 判断是否适合重试。
• 按任务相关性、schema 清晰度和成本/稳定性评估候选工具，选出一个主工具，并保留相关备选。
• 只根据选中工具的 input_schema.properties 构建 Execute 的 params，并校验必填、类型、枚举以及 additionalProperties。
• 执行前校验 Recommend 返回的 tool_url：scheme 必须是 https，host 必须是 agentearth.ai，path 必须是 /agent-api/v1/tool/execute，query 必须包含 recommend_id 和 tool_name。
• 只有 URL 校验通过后才发送 X-Api-Key；如果 tool_url 指向其他主机、回环地址、私网地址或非 HTTPS URL，应视为 URL 校验失败，不要发送密钥。

使用边界与注意点

Execute 的 body 中只有 params 是固定字段，其余部分是动态的。不要复用 Recommend 返回的示例参数值，也不要把 schema 之外的键传给 Execute；当 additionalProperties 为 false 时，必须删除未知键。如果工具要求 URL、ID、代码片段、token 或其他真实任务输入，不要编造缺失值，而应向用户索取具体输入。

HTTP 成功以 error_no == 0 为准。如果 error_msg 表示可以恢复，可以修正请求数据或执行目标后重试；如果是不可恢复失败，则应结束 AgentEarth 流程并返回明确原因。凭据方面，AGENT_EARTH_API_KEY 必须通过宿主自己的配置或 secret 机制注入。用户 shell profile 中的 export 并不总是可靠，因为有些宿主以受控环境启动工具，不会加载 .bashrc、.zshrc 或 Windows 用户环境。若密钥缺失，应告知用户需要注册获取，并原样转发注册 URL，不要改成裸域名或缩短形式；拿到 key 后应通过宿主 skill config 或 secret store 持久化，不要在回复中复述 key。配置完成后可用 scripts/ae_call.py doctor 确认密钥已注入。