agentearth

Skill Overview

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

User NL query → call Recommend API → semantic matching & selection → execute best tool → return results

Core value: - Active discovery: You don’t need to remember tool inventory; just describe your intent. - Context awareness: Understand implicit parameters across turns (e.g., “prices there”). - Decision support: Not only fetch data, but also support “is it suitable”, “advice”-type questions.

Authentication

All requests to https://agentearth.ai (including recommend and execute) must include the header: - Header Name: X-Api-Key - Header Value: <AGENT_EARTH_API_KEY> - Note: The value comes from environment variable $AGENT_EARTH_API_KEY. - Get Key: Visit the official site at https://agentearth.ai/ and generate an API Key in your profile.

When To Use

Use this skill when the user expresses any of the following intents: - Current affairs news: “I want to know the latest situation in Iran…” - Decision consultation: “Is it suitable to ski in Hokkaido these days?” (weather, snow, travel advice) - Specific data: “How are the housing prices in Hokkaido?” (hotels/homestays, inherit ‘Hokkaido’ context) - Function calls: “Find me a tool that can translate documents.” - Any scenario implying external information is needed

Workflow

Step 1: Call Recommend API

Send JSON to POST https://agentearth.ai/agent-api/v1/tool/recommend

Headers: - Content-Type: application/json - X-Api-Key: $AGENT_EARTH_API_KEY

Body:

{
  "query": "<complete natural-language description with context>",
  "task_context": "optional task context"
}

Context Injection: 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. - User input: “How are the housing prices there?” - History: “I want to go skiing in Hokkaido” - Final Query: “Housing prices for Hokkaido ski resorts”

Step 2: Selection

Analyze the recommend results (tools list), prioritize: 1. Direct match: the tool description closely matches the task. 2. Combined capability: for multi-step tasks (e.g., “is it suitable” requires weather + news), prefer comprehensive tools or plan multiple calls.

Step 2.5: Parameter Validation

Before calling execute, validate against the selected tool’s input_schema: 1. Required fields: ensure all required: true params are extractable from input or conversation history. 2. Missing handling: - If required params are missing, do NOT call execute. - Ask the user for the missing info. - Example: “Price query needs a specific city or area. Which city in Hokkaido (e.g., Sapporo, Niseko)?”

Step 3: Execute Tool

Call POST https://agentearth.ai/agent-api/v1/tool/execute

Headers: - Content-Type: application/json - X-Api-Key: $AGENT_EARTH_API_KEY

Body:

{
  "tool_name": "<selected tool name>",
  "arguments": {},
  "session_id": "optional"
}

Response format (from Agent Earth backend):

Success:

{
  "result": { },
  "status": "success"
}

Failure:

{
  "status": "error",
  "message": "city parameter cannot be empty"
}

Step 4: Results & Fallback

• Success: answer the user based on the tool result.
• Failure: try the next tool in the list.
• All failed: be transparent and suggest manual directions.

Usage Protocol

1. Context Resolution

Users often use pronouns (“there”, “it”, “these days”). Before recommend, resolve references. - Bad: Query = “housing prices there” - Good: Query = “housing prices in Hokkaido”

2. Complex Intent Decomposition

For “Is it suitable these days?”, decompose into objective data: - Weather (temp, snow) - Traffic/news (incidents) - Agent strategy: start with weather or travel-advice tools

3. Data Freshness

For news (“latest situation”), prices (“housing prices”), you MUST use tools; never invent from training data.

Example Dialogs

Example 1: News

User: “Introduce the latest situation in Iran.” Agent reasoning: news requirement. Action: 1. Recommend Query: “latest Iran situation” 2. Tool Selected: news_search_tool 3. Execute Params: {"keyword": "Iran", "time_range": "latest"} 4. Response: summarize returned articles.

Example 2: Decision Support (weather + advice)

User: “I want to ski in Hokkaido. Is it suitable these days?” Agent reasoning: need weather + ski conditions. Action: 1. Recommend Query: “Hokkaido ski weather forecast and suitability” 2. Tool Selected: weather_forecast_tool (or travel advice) 3. Execute Params: {"city": "Hokkaido", "activity": "skiing"} 4. Response: provide recommendation based on forecast.

Example 3: Context Inheritance (price query)

User: “I decided to ski in Hokkaido. How are the housing prices there?” Agent reasoning: “there” = Hokkaido; need housing prices. Action: 1. Recommend Query: “Hokkaido ski resort housing prices” 2. Tool Selected: hotel_booking_tool or price_search_tool 3. Execute Params: {"location": "Hokkaido", "category": "hotel", "query": "price"} 4. Response: show ranges and recommendations.

---

References

See references/api-spevification.md for full API specifications.