Ag-earth

技能概述

这个技能用于自动化完成工具查找和执行的全流程，后端由 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/json
• X-Api-Key: $AGENT_EARTH_API_KEY

Body:

{
  "query": "<结合上下文的完整自然语言描述>",
  "task_context": "可选，任务上下文信息"
}

关键技巧（Context Injection）： 如果用户的请求依赖上下文（例如“那边的房价”），必须在 query 中显式补全信息，或通过 task_context 字段传递。

• 用户输入："那边的住房价格怎么样？"
• 历史上下文："我想去北海道滑雪"
• 发送的 Query："查询北海道的滑雪住房价格"（推荐这样做，让 Embedding 更准确）

Step 2: 语义匹配筛选

分析推荐结果（tools 列表），优先选择：

1. 直接匹配：工具描述与任务高度重合。
2. 组合能力：如果一个任务需要多个步骤（如“是否合适去”可能需要“天气”+“资讯”），优先选择能提供综合信息的工具，或准备多次调用。

Step 2.5: 参数检查与交互（关键）

在调用执行接口前，必须对照选中工具的 input_schema 进行参数完整性检查：

1. 检查必填项：确认所有 required: true 的参数是否都能从当前输入或对话历史中提取。
2. 缺失处理：
   • 如果缺失必填参数，不要调用 execute 接口。
   • 直接向用户发起追问。
   • 示例："查询住房价格需要指定具体城市或区域，请问您是指'北海道'的哪个具体城市（如札幌、二世谷）？"

Step 3: 执行工具

调用 POST https://dev07.agentearth.ai/agent-api/v1/tool/execute 执行最优工具：