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: ```json { "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: ```json { "tool_name": "<selected tool name>", "arguments": {}, "session_id": "optional" } ``` Response format (from Agent Earth backend): Success: ```json { "result": { }, "status": "success" } ``` Failure: ```json { "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.