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 官方网站](https://agentearth.ai/)，在个人主页中添加 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:** ```json { "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` 执行最优工具： **Headers:** - `Content-Type: application/json` - `X-Api-Key: $AGENT_EARTH_API_KEY` **Body:** ```json { "tool_name": "<选中的工具名称>", "arguments": { // 从用户请求中提取必要参数，如无特定参数传空对象 {} "city": "北海道", // 示例：从上下文提取 "query": "伊朗战况" // 示例：针对新闻类工具 }, "session_id": "可选，会话 ID" } ``` 执行接口的响应格式（与 Agent Earth 后端对应）： 成功时： ```json { "result": { /* 工具执行的具体结果 */ }, "status": "success" } ``` 失败时示例： ```json { "status": "error", "message": "参数 city 不能为空" } ``` ### Step 4: 结果处理与降级 - **成功**：基于工具返回的数据回答用户。 - **失败**：尝试列表中的下一个工具。 - **全部失败**：诚实告知用户无法获取信息，并建议手动查询方向。 ## 使用协议 (Usage Protocol) ### 1. 多轮对话中的上下文继承 用户常会使用代词（“那边”、“它”、“这两天”）。在调用 `recommend` 之前，**必须**先解析指代关系。 - **Bad**: Query = "那边的住房价格" -> 推荐结果可能不准确。 - **Good**: Query = "北海道的住房价格" -> 推荐结果精准。 ### 2. 复杂意图拆解 对于“这两天合适去吗？”这类问题，通常需要拆解为客观数据查询： - 天气查询（温度、风雪） - 交通/新闻查询（是否有突发事件） - **Agent 策略**：先搜索“天气”或“旅游建议”类工具。 ### 3. 数据时效性 对于新闻（“最新战况”）、价格（“住房价格”）类问题，**必须**使用工具，严禁使用模型训练数据编造。 ## 示例对话 ### 示例 1：时事新闻查询 **用户**: "我想知道最新的伊朗战况，帮我介绍一下" **Agent 思考**: 这是一个新闻查询需求。 **Action**: 1. Recommend Query: "最新伊朗战况新闻" 2. Tool Selected: `news_search_tool` 3. Execute Params: `{"keyword": "伊朗战况", "time_range": "latest"}` 4. Response: 基于工具返回的新闻摘要回答。 ### 示例 2：决策支持（天气+建议） **用户**: "我想去北海道滑雪，这两天合适去吗？" **Agent 思考**: 需要查询北海道的天气和滑雪场状况。 **Action**: 1. Recommend Query: "北海道滑雪天气预报及适宜度" 2. Tool Selected: `weather_forecast_tool` (或类似的旅游建议工具) 3. Execute Params: `{"city": "Hokkaido", "activity": "skiing"}` 4. Response: "根据天气预报，北海道未来两天有大雪，气温-5度，非常适合滑雪，但需注意防寒..." ### 示例 3：上下文继承（价格查询） **用户**: "我决定去北海道滑雪了，那边的住房价格怎么样？" **Agent 思考**: 用户指的“那边”是“北海道”。需求是“住房价格”。 **Action**: 1. Recommend Query: "北海道滑雪度假村住房价格" (Context Injection) 2. Tool Selected: `hotel_booking_tool` 或 `price_search_tool` 3. Execute Params: `{"location": "Hokkaido", "category": "hotel", "query": "price"}` 4. Response: 展示查询到的价格范围和推荐。 --- ## 参考资料 详见 `references/api-specification.md` 了解 API 详细规格。