Agentearth

\r \r

Skill Overview\r

\r This skill automates the full workflow of tool discovery and execution, backed by Agent Earth. The base address is https://agentearth.ai:\r \r

User NL query → call Recommend API → semantic matching & selection → execute best tool → return results\r
```\r
\r
Core value:\r
- Active discovery: You don’t need to remember tool inventory; just describe your intent.\r
- Context awareness: Understand implicit parameters across turns (e.g., “prices there”).\r
- Decision support: Not only fetch data, but also support “is it suitable”, “advice”-type questions.\r
\r
## Authentication\r
\r
All requests to `https://agentearth.ai` (including recommend and execute) must include the header:\r
- Header Name: `X-Api-Key`\r
- Header Value: `\x3CAGENT_EARTH_API_KEY>`\r
- Note: The value comes from environment variable `$AGENT_EARTH_API_KEY`.\r
- Get Key: Visit the official site at https://agentearth.ai/ and generate an API Key in your profile.\r
\r
## When To Use\r
\r
Use this skill when the user expresses any of the following intents:\r
- Current affairs news: “I want to know the latest situation in Iran…”\r
- Decision consultation: “Is it suitable to ski in Hokkaido these days?” (weather, snow, travel advice)\r
- Specific data: “How are the housing prices in Hokkaido?” (hotels/homestays, inherit ‘Hokkaido’ context)\r
- Function calls: “Find me a tool that can translate documents.”\r
- Any scenario implying external information is needed\r
\r
## Workflow\r
\r
### Step 1: Call Recommend API\r
\r
Send JSON to `POST https://agentearth.ai/agent-api/v1/tool/recommend`\r
\r
Headers:\r
- `Content-Type: application/json`\r
- `X-Api-Key: $AGENT_EARTH_API_KEY`\r
\r
Body:\r
\r
```json\r
{\r
  "query": "\x3Ccomplete natural-language description with context>",\r
  "task_context": "optional task context"\r
}\r
```\r
\r
Context Injection:\r
If the user’s request depends on context (e.g., “housing prices there”), you MUST explicitly complete the information in `query`, or pass via `task_context`.\r
- User input: “How are the housing prices there?”\r
- History: “I want to go skiing in Hokkaido”\r
- Final Query: “Housing prices for Hokkaido ski resorts”\r
\r
### Step 2: Selection\r
\r
Analyze the recommend results (`tools` list), prioritize:\r
1. Direct match: the tool description closely matches the task.\r
2. Combined capability: for multi-step tasks (e.g., “is it suitable” requires weather + news), prefer comprehensive tools or plan multiple calls.\r
\r
### Step 2.5: Parameter Validation\r
\r
Before calling execute, validate against the selected tool’s `input_schema`:\r
1. Required fields: ensure all `required: true` params are extractable from input or conversation history.\r
2. Missing handling:\r
   - If required params are missing, do NOT call execute.\r
   - Ask the user for the missing info.\r
   - Example: “Price query needs a specific city or area. Which city in Hokkaido (e.g., Sapporo, Niseko)?”\r
\r
### Step 3: Execute Tool\r
\r
Call `POST https://agentearth.ai/agent-api/v1/tool/execute`\r
\r
Headers:\r
- `Content-Type: application/json`\r
- `X-Api-Key: $AGENT_EARTH_API_KEY`\r
\r
Body:\r
\r
```json\r
{\r
  "tool_name": "\x3Cselected tool name>",\r
  "arguments": {},\r
  "session_id": "optional"\r
}\r
```\r
\r
Response format (from Agent Earth backend):\r
\r
Success:\r
\r
```json\r
{\r
  "result": { },\r
  "status": "success"\r
}\r
```\r
\r
Failure:\r
\r
```json\r
{\r
  "status": "error",\r
  "message": "city parameter cannot be empty"\r
}\r
```\r
\r
### Step 4: Results & Fallback\r
\r
- Success: answer the user based on the tool result.\r
- Failure: try the next tool in the list.\r
- All failed: be transparent and suggest manual directions.\r
\r
## Usage Protocol\r
\r
### 1. Context Resolution\r
Users often use pronouns (“there”, “it”, “these days”). Before `recommend`, resolve references.\r
- Bad: Query = “housing prices there”\r
- Good: Query = “housing prices in Hokkaido”\r
\r
### 2. Complex Intent Decomposition\r
For “Is it suitable these days?”, decompose into objective data:\r
- Weather (temp, snow)\r
- Traffic/news (incidents)\r
- Agent strategy: start with weather or travel-advice tools\r
\r
### 3. Data Freshness\r
For news (“latest situation”), prices (“housing prices”), you MUST use tools; never invent from training data.\r
\r
## Example Dialogs\r
\r
### Example 1: News\r
User: “Introduce the latest situation in Iran.”\r
Agent reasoning: news requirement.\r
Action:\r
1. Recommend Query: “latest Iran situation”\r
2. Tool Selected: `news_search_tool`\r
3. Execute Params: `{"keyword": "Iran", "time_range": "latest"}`\r
4. Response: summarize returned articles.\r
\r
### Example 2: Decision Support (weather + advice)\r
User: “I want to ski in Hokkaido. Is it suitable these days?”\r
Agent reasoning: need weather + ski conditions.\r
Action:\r
1. Recommend Query: “Hokkaido ski weather forecast and suitability”\r
2. Tool Selected: `weather_forecast_tool` (or travel advice)\r
3. Execute Params: `{"city": "Hokkaido", "activity": "skiing"}`\r
4. Response: provide recommendation based on forecast.\r
\r
### Example 3: Context Inheritance (price query)\r
User: “I decided to ski in Hokkaido. How are the housing prices there?”\r
Agent reasoning: “there” = Hokkaido; need housing prices.\r
Action:\r
1. Recommend Query: “Hokkaido ski resort housing prices”\r
2. Tool Selected: `hotel_booking_tool` or `price_search_tool`\r
3. Execute Params: `{"location": "Hokkaido", "category": "hotel", "query": "price"}`\r
4. Response: show ranges and recommendations.\r
\r
---\r
\r
## References\r
\r
See `references/api-spevification.md` for full API specifications.\r