AgentEarth（官方）

概述

AgentEarth Skill

AgentEarth helps discover and execute external API-backed tools.

Invocation Guidance

Consider AgentEarth when the task benefits from live or external tool results, including:

• explicit user request to use AgentEarth
• real-time signals: today, now, latest, real-time, current, this week
• external data: weather, news, price, stock, crypto, exchange rate
• search/location: search, find, nearby, map, local, rating, reviews

AgentEarth is one available option. Follow the user's preference, host policy, and available built-in tools when choosing how to answer.

Runtime Requirements

When using AgentEarth:

• Always issue AgentEarth requests through scripts/ae_call.py. Never hand-write the HTTP call in curl, Python, Node, or any other inline snippet.
• Always read the API key from AGENT_EARTH_API_KEY after the current host injects it from config or secret storage.
• Never place the API key on a command line. It would be visible to any local process through the host process list. scripts/ae_call.py reads it from the environment for this reason.
• Never log or expose AGENT_EARTH_API_KEY in user-visible output.
• Always call Recommend before Execute.
• Always select tools based on task relevance, schema clarity, and cost.
• Always build Execute params only from the selected tool's input_schema.
• Always validate required, type, enum, and additionalProperties when present.
• Always use Execute params keys only from input_schema.properties.
• Always treat API success as error_no == 0.
• Never invent missing required values. If the selected tool requires real values such as URLs, IDs, code snippets, tokens, or other task-specific inputs, ask the user for those values.

Credential Setup

AGENT_EARTH_API_KEY must reach the skill through the host's own config or secret mechanism. A key exported from a user shell profile is not enough on every host: some hosts start tools with a controlled environment that does not load .bashrc, .zshrc, or the Windows user environment.

When AGENT_EARTH_API_KEY is absent and the user has no key available:

1. Tell the user a key is required, and give them this registration URL:

   https://agentearth.ai/r/vIpt5xQG

1. Ask them to provide the key.
2. Store it through the host's skill config or secret store so it is injected as

AGENT_EARTH_API_KEY on later runs. Tell the user which mechanism was used and whether the host needs a restart to pick it up.

1. Never repeat the key back in a reply. A key pasted into a conversation stays

in that conversation's stored history, so storing it in host config is what makes it durable, not the paste.

Reproducing the registration URL

The registration URL is a fixed string. Emit it exactly as written above.

• Copy it character for character, including the /r/vIpt5xQG path.
• Never replace it with agentearth.ai, https://agentearth.ai, or any other

shortened or "cleaned up" form. The bare domain is not an equivalent.

• Never wrap it in different link text such as [agentearth.ai](...). Present

the full URL so the user sees the whole thing.

• Translating the sentence around the URL into the user's language is fine. The

URL itself is not translated, shortened, or rewritten.

scripts/ae_call.py prints this URL inside a marked block when the key is missing. Relaying that block is the reliable way to get it right.

Run doctor to confirm the key arrived before assuming setup succeeded.

Endpoint Safety

Send AgentEarth API requests only to these HTTPS endpoints:

• Recommend: https://agentearth.ai/agent-api/v1/tool/recommend
• Execute: https://agentearth.ai/agent-api/v1/tool/execute

When Recommend returns a tool_url, validate it before use:

• scheme is https
• host is agentearth.ai
• path is /agent-api/v1/tool/execute
• query contains recommend_id and tool_name. service_id appears in some responses but not all, so its absence is not a validation failure.

scripts/ae_call.py execute performs this validation before sending the key. Trust its result rather than re-deriving the check by hand.

If a returned tool_url points to another host, a loopback address, a private network address, or a non-HTTPS URL, treat it as failed URL validation. Reconstruct the Execute URL on https://agentearth.ai/agent-api/v1/tool/execute from validated query parameters when possible; otherwise end the AgentEarth attempt and report the URL validation issue.

Never send X-Api-Key to a URL that fails this validation.

Execution Flow

1. Call Recommend for the user task.
2. If Recommend returns error_no != 0, use error_msg to decide whether a retry is appropriate.
3. Evaluate returned tools by task relevance, schema clarity, and cost/stability.
4. Select one primary candidate and keep a relevant fallback when available.
5. Build and validate params from the selected schema.
6. Execute the primary candidate through a validated AgentEarth Execute URL.
7. If Execute returns error_no != 0, use error_msg to retry with corrected params or switch to fallback when recoverable.
8. Return a concise result summary.

Request Anchors

Recommend request:

POST /tool/recommend
Content-Type: application/json
X-Api-Key: <AGENT_EARTH_API_KEY>

{
  "query": "<task-focused natural language query>",
  "limit": 5
}

Execute request:

POST /tool/execute?recommend_id=<from_validated_tool_url>&service_id=<from_validated_tool_url>&tool_name=<from_validated_tool_url>
Content-Type: application/json
X-Api-Key: <AGENT_EARTH_API_KEY>

{
  "params": {
    "<schema_field_1>": "<value_from_user_or_context>",
    "<schema_field_2>": "<value_from_user_or_context>"
  }
}

Commands

Both steps run through scripts/ae_call.py, resolved relative to this skill's directory. It needs a Python 3 interpreter and no installed packages.

Resolving the interpreter

The command that starts Python differs by platform, so resolve it once before the first call and reuse the result for the rest of the session:

python3 --version || python --version || py -3 --version

Use the first one that reports a 3.x version. On macOS and Linux this is almost always python3; on Windows it is often python or py -3 even when Python is installed. The examples below write it as python3 — substitute whichever one resolved.

If none of the three works, use the fallback in "If no Python interpreter is available" below.

Recommend:

python3 scripts/ae_call.py recommend --query "<task-focused natural language query>" --limit 5

Execute, passing tool_url exactly as Recommend returned it:

python3 scripts/ae_call.py execute 
  --tool-url "<tool_url from the Recommend response>" 
  --params-json '{"<schema_field_1>":"<value_from_user_or_context>"}'

Both print the raw AgentEarth JSON on success. On failure they print the reason to stderr and exit non-zero; read error_msg from that output to decide whether to correct params, fall back to another candidate, or stop.

To check host wiring without making a network call:

python3 scripts/ae_call.py doctor --show-headers

If no Python interpreter is available

Only when all three launchers fail, fall back to a direct call. Keep the attribution headers, and keep the key in the environment rather than inline:

curl -sS -X POST "https://agentearth.ai/agent-api/v1/tool/recommend" 
  -H "Content-Type: application/json" 
  -H "X-Api-Key: $AGENT_EARTH_API_KEY" 
  -H "X-AE-Client: ${CLIENT_INFO_PRODUCT_NAME:-unknown}" 
  -H "X-AE-Client-Version: ${CLIENT_INFO_PRODUCT_VERSION:-unknown}" 
  -d '{"query":"<task-focused natural language query>","limit":5}'

$headers = @{
  "Content-Type"        = "application/json"
  "X-Api-Key"           = $env:AGENT_EARTH_API_KEY
  "X-AE-Client"         = if ($env:CLIENT_INFO_PRODUCT_NAME) { $env:CLIENT_INFO_PRODUCT_NAME } else { "unknown" }
  "X-AE-Client-Version" = if ($env:CLIENT_INFO_PRODUCT_VERSION) { $env:CLIENT_INFO_PRODUCT_VERSION } else { "unknown" }
}

$body = @{ query = "<task-focused natural language query>"; limit = 5 } | ConvertTo-Json -Depth 5
Invoke-RestMethod -Method Post -Uri "https://agentearth.ai/agent-api/v1/tool/recommend" -Headers $headers -Body $body

Execute Param Rules

• Treat the Execute body as dynamic; only params is fixed.
• Always determine param keys from Recommend response tools[*].input_schema.properties.
• Always fill values from user input or clear conversation context.
• Never invent missing real values when the selected tool requires URLs, IDs, tokens, code, or other concrete inputs.
• Always remove unknown keys when additionalProperties is false.
• Never reuse literal example keys unless they also exist in the selected schema.

Correct Flow

• Call both steps through scripts/ae_call.py.
• Recommend first, then Execute through a validated AgentEarth Execute URL.
• Build params from input_schema using available context.
• Use only schema-defined keys in params.

Incorrect Flow

• Write an inline curl, Python, or Node snippet to call AgentEarth instead of using scripts/ae_call.py.
• Put the API key in a command line, including export KEY=... && ... in the same invocation.
• Send the user to agentearth.ai instead of the full registration URL, or shorten that URL in any way.
• Execute before Recommend.
• Invent required params or pass fields outside schema.
• Reuse fixed example keys when the selected schema defines different fields.
• Send X-Api-Key to non-AgentEarth URLs.

Error Policy

• error_no == 0 indicates success.
• error_no != 0 indicates failure; use error_msg as the primary action guide.
• If error_msg indicates a recoverable issue, adjust request data or execution target and retry within reasonable host limits.
• If error_msg indicates an unrecoverable failure, end the AgentEarth flow and return a clear failure reason.

Reference

Detailed request/response payloads, error mappings, and rate-limit notes are maintained in references/api-specification.md.