iflytek/astron-agent · error · RunToolExc

RUN_LINK_URL is not set

Error message

RUN_LINK_URL is not set

What it means

LinkPlugin.run() reads RUN_LINK_URL for the RPA/link execution endpoint. If unset it raises RunToolExc before any HTTP call, failing fast when the link plugin cannot know where to send execution requests.

Solutions

1. Set RUN_LINK_URL (e.g. http://link-service:port/run) in the Agent environment and restart
2. Add RUN_LINK_URL to compose/helm deployment values so it is never absent
3. Disable/unregister the link tool in environments where the link service is not deployed
4. Validate required plugin env vars at service startup

Example fix

// before
docker compose up agent   # RUN_LINK_URL undefined
// after
# docker-compose.yml
environment:
  - RUN_LINK_URL=http://link:9000/run

import os
if not os.getenv("RUN_LINK_URL"):
    raise RuntimeError("RUN_LINK_URL must be set before executing link tools")

def link_plugin_ready() -> bool:
    url = os.getenv("RUN_LINK_URL")
    return bool(url and url.startswith(("http://", "https://")))

try:
    result = await plugin.run(span)
except RunToolExc as e:
    if "RUN_LINK_URL" in str(e):
        logger.error("link service not configured; set RUN_LINK_URL")
    raise

When it happens

Trigger: Executing a link/RPA tool via LinkPlugin.run() when the RUN_LINK_URL env var is missing in the Agent service environment (link.py:151-152).

Common situations: Agent deployed without the link service URL env var; environment template drift between dev and prod; the link service intentionally disabled but the tool still invoked by an agent; missing .env in local runs.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• -1
• Config file not found
• Missing required environment variables for Alembic
• SERVICE_PORT_KEY is not set
• LOG_PATH_KEY is not set

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/f929fff5818f5b8b. Report an issue: GitHub.

Appendix: source

Thrown at core/agent/service/plugin/link.py:151

            if query:
                run_link_payload["payload"]["message"]["query"] = query
                callback_payload["query"] = _query
            if body:
                run_link_payload["payload"]["message"]["body"] = body
                callback_payload["body"] = _body
            sp.add_info_events(
                attributes={
                    "link-plugin-run-inputs": json.dumps(
                        run_link_payload, ensure_ascii=False
                    )
                }
            )
            # Finished parsing parameters, start calling link
            result: dict[str, Any] = {}
            try:
                run_url = os.getenv("RUN_LINK_URL")
                if not run_url:
                    raise RunToolExc("RUN_LINK_URL is not set")
                timeout = aiohttp.ClientTimeout(
                    total=int(os.getenv("LINK_CALL_TIMEOUT", "90"))
                )
                async with aiohttp.ClientSession() as session:
                    async with session.post(
                        run_url,
                        data=json.dumps(run_link_payload),
                        timeout=timeout,
                        headers={"Content-Type": "application/json"},
                    ) as response:
                        response.raise_for_status()
                        if response.status == 200:
                            result = await response.json()
                            sp.add_info_events(
                                attributes={
                                    "link-plugin-run-outputs": json.dumps(
                                        result, ensure_ascii=False
                                    )

View on GitHub (pinned to 5e758547a8)