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.