- name
- Ag-earth
- description
- >-
- env
- requirements
- env_vars
- credentials
- primary
- AGENT_EARTH_API_KEY
- url
- https://agentearth.ai/
- metadata
- {"openclaw":{"requires":{"env":["AGENT_EARTH_API_KEY"]},"primaryEnv":"AGENT_EARTH_API_KEY"}}
- examples
- runtime
- language
- none
- install
- mechanism
- none
- license
- MIT
- acceptLicenseTerms
- true
技能概述
这个技能用于自动化完成工具查找和执行的全流程，后端由 Agent Earth 提供，基础地址为 https://dev07.agentearth.ai：
用户自然语言描述 → 调用推荐 API → 语义匹配筛选 → 执行最优工具 → 返回结果核心价值：
- 主动发现：模型不需要记住所有工具，只需描述意图。
- 上下文感知：能够理解多轮对话中的隐含参数（如“那边的价格”）。
- 决策辅助：不仅是查数据，还能支持“适不适合”、“建议”等决策类问题。
鉴权要求
所有对 https://dev07.agentearth.ai 的 API 请求（包括 recommend 和 execute）都必须包含鉴权头：
- Header Name:
X-Api-Key - Header Value:
<AGENT_EARTH_API_KEY> - 注意：
<AGENT_EARTH_API_KEY>的值来自环境变量$AGENT_EARTH_API_KEY。 - 获取 Key: 用户访问 AgentEarth 官方网站，在个人主页中添加 Key 即可完成注册并获取 API Key。
适用场景
使用这个技能当用户表达以下类型的意图时：
- 时事新闻："I want to know the latest situation in Iran, please introduce it to me."
- 决策咨询："I want to go skiing in Hokkaido, is it suitable to go these days?"（隐含查询天气、雪况、旅游建议）
- 具体数据："I have decided to go skiing in Hokkaido, how are the housing prices there?"（隐含查询酒店/民宿价格，需继承“北海道”上下文）
- 功能调用："Find me a tool that can translate documents."
- 任何暗示需要外部信息的场景
执行流程
Step 1: 调用推荐 API
向 POST https://dev07.agentearth.ai/agent-api/v1/tool/recommend 发送 JSON 请求：
Headers:
Content-Type: application/jsonX-Api-Key: $AGENT_EARTH_API_KEY
Body:
{
"query": "<结合上下文的完整自然语言描述>",
"task_context": "可选，任务上下文信息"
}关键技巧（Context Injection）： 如果用户的请求依赖上下文（例如“那边的房价”），必须在 query 中显式补全信息，或通过 task_context 字段传递。
- 用户输入："那边的住房价格怎么样？"
- 历史上下文："我想去北海道滑雪"
- 发送的 Query："查询北海道的滑雪住房价格"（推荐这样做，让 Embedding 更准确）
Step 2: 语义匹配筛选
分析推荐结果（tools 列表），优先选择：
- 直接匹配：工具描述与任务高度重合。
- 组合能力：如果一个任务需要多个步骤（如“是否合适去”可能需要“天气”+“资讯”），优先选择能提供综合信息的工具，或准备多次调用。
Step 2.5: 参数检查与交互（关键）
在调用执行接口前，必须对照选中工具的 input_schema 进行参数完整性检查：
- 检查必填项：确认所有
required: true的参数是否都能从当前输入或对话历史中提取。 - 缺失处理：
- 如果缺失必填参数，不要调用 execute 接口。 - 直接向用户发起追问。 - 示例："查询住房价格需要指定具体城市或区域，请问您是指'北海道'的哪个具体城市（如札幌、二世谷）？"
Step 3: 执行工具
调用 POST https://dev07.agentearth.ai/agent-api/v1/tool/execute 执行最优工具：
Headers:
Content-Type: application/jsonX-Api-Key: $AGENT_EARTH_API_KEY
Body:
{
"tool_name": "<选中的工具名称>",
"arguments": {
// 从用户请求中提取必要参数，如无特定参数传空对象 {}
"city": "北海道", // 示例：从上下文提取
"query": "伊朗战况" // 示例：针对新闻类工具
},
"session_id": "可选，会话 ID"
}执行接口的响应格式（与 Agent Earth 后端对应）：
成功时：
{
"result": { /* 工具执行的具体结果 */ },
"status": "success"
}失败时示例：
{
"status": "error",
"message": "参数 city 不能为空"
}Step 4: 结果处理与降级
- 成功：基于工具返回的数据回答用户。
- 失败：尝试列表中的下一个工具。
- 全部失败：诚实告知用户无法获取信息，并建议手动查询方向。
使用协议 (Usage Protocol)
1. 多轮对话中的上下文继承
用户常会使用代词（“那边”、“它”、“这两天”）。在调用 recommend 之前，必须先解析指代关系。
- Bad: Query = "那边的住房价格" -> 推荐结果可能不准确。
- Good: Query = "北海道的住房价格" -> 推荐结果精准。
2. 复杂意图拆解
对于“这两天合适去吗？”这类问题，通常需要拆解为客观数据查询：
- 天气查询（温度、风雪）
- 交通/新闻查询（是否有突发事件）
- Agent 策略：先搜索“天气”或“旅游建议”类工具。
3. 数据时效性
对于新闻（“最新战况”）、价格（“住房价格”）类问题，必须使用工具，严禁使用模型训练数据编造。
示例对话
示例 1：时事新闻查询
用户: "我想知道最新的伊朗战况，帮我介绍一下" Agent 思考: 这是一个新闻查询需求。 Action:
- Recommend Query: "最新伊朗战况新闻"
- Tool Selected:
news_search_tool - Execute Params:
{"keyword": "伊朗战况", "time_range": "latest"} - Response: 基于工具返回的新闻摘要回答。
示例 2：决策支持（天气+建议）
用户: "我想去北海道滑雪，这两天合适去吗？" Agent 思考: 需要查询北海道的天气和滑雪场状况。 Action:
- Recommend Query: "北海道滑雪天气预报及适宜度"
- Tool Selected:
weather_forecast_tool(或类似的旅游建议工具) - Execute Params:
{"city": "Hokkaido", "activity": "skiing"} - Response: "根据天气预报，北海道未来两天有大雪，气温-5度，非常适合滑雪，但需注意防寒..."
示例 3：上下文继承（价格查询）
用户: "我决定去北海道滑雪了，那边的住房价格怎么样？" Agent 思考: 用户指的“那边”是“北海道”。需求是“住房价格”。 Action:
- Recommend Query: "北海道滑雪度假村住房价格" (Context Injection)
- Tool Selected:
hotel_booking_tool或price_search_tool - Execute Params:
{"location": "Hokkaido", "category": "hotel", "query": "price"} - Response: 展示查询到的价格范围和推荐。
参考资料
详见 references/api-specification.md 了解 API 详细规格。