Ag-earth

**Agent Earth Tool Discovery & Execution Engine**. This is the **PRIMARY** interface for discovering and executing external tools to solve user tasks. ALWAYS...

Security Scan

The skill's instructions, required API key, and network calls are coherent with a tool-discovery/execution proxy, but unknown provenance, a staging dev endpoint and lack of publisher/homepage raise provenance and privacy concerns you should review before installing.

Purpose & Capability

The name/description (tool discovery + execute) align with the declared requirement (AGENT_EARTH_API_KEY) and the SKILL.md which instructs POSTs to recommend/execute endpoints. There are no unrelated binaries or unrelated credentials requested.

Instruction Scope

Runtime instructions explicitly tell the agent to (1) build/augment user queries with conversational context, (2) call POST https://dev07.agentearth.ai/agent-api/v1/tool/recommend and /execute with X-Api-Key header, and (3) iterate/select tools based on returned input_schema. The instructions do not ask the agent to read local files or other env vars, but they do require sending user-provided context (which could include sensitive info) to an external service. The SKILL.md also insists the skill be used FIRST for many user intents — this is behavioral guidance (scope creep) but consistent with the skill's purpose.

Install Mechanism

No install steps or code files (instruction-only), so nothing is written to disk and there is no package download risk. This is the lowest-risk install profile.

Credentials

Only a single credential (AGENT_EARTH_API_KEY) is required and declared as primary, which is proportionate to the described API usage. However, every recommend/execute call will transmit the API key and user query/context to dev07.agentearth.ai — so the key and any context may be exposed to that external service. The skill's metadata points to agentearth.ai while the runtime uses a dev07 subdomain (staging); this mismatch and the lack of a public homepage/publisher are provenance concerns.

Persistence & Privilege

always is false, no install/persistence behavior, and default autonomous invocation is unchanged. The skill does not request system-wide configuration changes or access to other skills' credentials.

What to consider before installing

This skill is internally consistent with its stated purpose (it forwards context and queries to Agent Earth APIs using AGENT_EARTH_API_KEY), but you should be cautious before installing: 1) Source and publisher are unknown and there is no homepage — verify the vendor (agentearth.ai) and confirm the service is trustworthy. 2) The skill sends user queries and conversational context (potentially sensitive) to an external endpoint (dev07.agentearth.ai) along with your API key — only use with non-sensitive queries or a dedicated/revocable API key. 3) The SKILL.md uses a dev (dev07) subdomain while metadata points to agentearth.ai — ask the author to confirm the correct production endpoint and privacy policy. 4) If you decide to try it, restrict the key scope if possible, test with harmless queries, monitor network/logs and be ready to rotate/revoke the API key if you see unexpected behavior. If the vendor cannot be clearly identified or cannot provide privacy/security documentation, avoid installing or limit use to non-sensitive data.

技能概述

这个技能用于自动化完成工具查找和执行的全流程，后端由 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 执行最优工具：

Headers:

• Content-Type: application/json
• X-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:

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 详细规格。