From 453cb60d379d252f4317bb0f2e460e9390d0369e Mon Sep 17 00:00:00 2001 From: Kaosiso Ezealigo Date: Mon, 6 Jul 2026 17:21:07 +0200 Subject: [PATCH 1/4] fix(build-agent): stop hardcoding cloud host in runtime remediation Traced to SKILL.md's "First run: credentials" section, which uses https://cloud.agenta.ai as the example for initial API-key setup. When a later runtime failure calls for telling the user to go add something to their Agenta project (e.g. a vault key), that same cloud URL was getting reused out of context instead of the user's actual configured $AGENTA_HOST - sending a self-hosted user to look in the wrong place entirely. Reproduced 3/3 times against a self-hosted instance during QA testing. SKILL.md now explicitly marks that URL as initial-setup-only, right where it's introduced, and adds a hard rule: any later remediation must reference the user's actual $AGENTA_HOST, not a hardcoded cloud URL. --- skills/build-agent/SKILL.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/skills/build-agent/SKILL.md b/skills/build-agent/SKILL.md index ed41892..6be9d15 100644 --- a/skills/build-agent/SKILL.md +++ b/skills/build-agent/SKILL.md @@ -41,6 +41,12 @@ self-hosts (it defaults to Agenta cloud, `https://cloud.agenta.ai`). - **Hand them a block to paste:** give them the lines to `export`, or the `.env` contents to create themselves. - Never print or commit the key. Add `.env` to `.gitignore` if the directory is a repo. +- **`https://cloud.agenta.ai` above is a one-time example for INITIAL setup only.** If a + later runtime error tells you to add a credential to the project vault (or anything else + that means "go to your Agenta project"), point the user at their actual configured + `$AGENTA_HOST` — read it from the environment/`.env`, don't repeat the cloud URL from this + section by habit. A self-hosted user sent to `cloud.agenta.ai` for a vault that lives on + their own domain will not find what you told them to look for. **2. Prerequisites.** Run `bash scripts/check-prereqs.sh`. It verifies `bash`, `curl`, and `jq` are installed. On a miss it prints the exact install command for the user's platform; @@ -168,6 +174,11 @@ Keep to the loop above for a simple agent. Read one of these only when the task - **Crons are UTC, five fields, one-minute floor.** Convert the user's local time yourself. - **needs_auth means stop.** If a needed connection is not `ready`, stop and ask the user to connect it. That is the whole job for that step. +- **Remediation guidance always uses the user's actual `$AGENTA_HOST`, never a hardcoded + cloud URL.** The `https://cloud.agenta.ai` example in the credentials section above is for + *initial* setup only. If a later runtime failure calls for telling the user to go add + something in their Agenta project (a vault key, a setting), point them at their actual + configured host — a self-hosted user sent to the cloud URL will look in the wrong place. - **Discovery is a search, not an oracle.** `discover-tools.sh` / `discover-triggers.sh` return high-recall best guesses over the live catalog. The matched **connection state** is reliable; the matched **integration and action** are not always right. A search matches on words: "save From f5039526d097a1e18cb76eb0afc5dad623eb46ad Mon Sep 17 00:00:00 2001 From: Kaosiso Ezealigo Date: Tue, 7 Jul 2026 10:47:42 +0200 Subject: [PATCH 2/4] Clarify AGENTA_HOST vs AGENTA_API_URL, merge main Per review feedback (jp asked why the skill uses AGENTA_HOST instead of AGENTA_API_URL): these scripts curl the public REST API directly from outside Agenta's own infrastructure, the same way the SDK derives its own api_url from host + "/api" (sdks/python/agenta/sdk/utils/init.py). AGENTA_API_URL is a different, internal override used when a workflow running INSIDE Agenta's infra needs to reach the API at a different address than the public host (e.g. docker-internal networking on a self-hosted install) - it doesn't apply to an external caller hitting the public REST API, which is all this skill ever does. Added a clarifying note in both SKILL.md and lib.sh's header comment so this doesn't get relitigated. Also merges main to pick up #12/#14, already merged. --- skills/build-agent/SKILL.md | 9 +++++++++ skills/build-agent/scripts/lib.sh | 5 +++++ 2 files changed, 14 insertions(+) diff --git a/skills/build-agent/SKILL.md b/skills/build-agent/SKILL.md index 4f57b5c..c89cd6b 100644 --- a/skills/build-agent/SKILL.md +++ b/skills/build-agent/SKILL.md @@ -31,6 +31,15 @@ Do these two things once, before any build. **1. Credentials.** The scripts need `AGENTA_API_KEY`, and `AGENTA_HOST` only if the user self-hosts (it defaults to Agenta cloud, `https://cloud.agenta.ai`). +`AGENTA_HOST` is the right variable here, not `AGENTA_API_URL`. These scripts call the +public REST API directly from outside Agenta's own infrastructure (your machine, CI, and so +on) the same way the Agenta SDK derives its own API URL: host + `/api`. `AGENTA_API_URL` is a +different, internal override the SDK uses when a workflow it runs *inside* Agenta's +infrastructure needs to reach the API at a different address than the public host (for +example, docker-internal networking on a self-hosted install) — it does not apply to a caller +hitting the public REST API from outside, which is all this skill ever does. Do not swap +`AGENTA_HOST` for `AGENTA_API_URL` here. + - Ask the user for their API key. Point them to it: the **API keys** page in their Agenta project settings (on cloud, under `https://cloud.agenta.ai`). Ask for the host URL only if they self-host, in which case it is their own Agenta domain. diff --git a/skills/build-agent/scripts/lib.sh b/skills/build-agent/scripts/lib.sh index 71f4e57..1083213 100755 --- a/skills/build-agent/scripts/lib.sh +++ b/skills/build-agent/scripts/lib.sh @@ -7,6 +7,11 @@ # AGENTA_API_KEY required. From your Agenta project settings (API keys). # AGENTA_HOST optional. Defaults to Agenta cloud. Set it only if self-hosting. # +# AGENTA_HOST, not AGENTA_API_URL: these scripts curl the public REST API directly from +# outside Agenta's infra, the same way the SDK derives its own api_url (host + "/api"). +# AGENTA_API_URL is a different, internal override for a workflow running INSIDE Agenta's +# infra that needs a different internal address than the public host. Not relevant here. +# # Precedence: values already in the environment win. If AGENTA_API_KEY is not in the # environment, the kit falls back to a .env file (AGENTA_ENV_FILE, then ./.env, then a # .env next to these scripts). The build-agent skill can write that .env for you. From a0da54c4faf26adf1d4a69580a29b0c5ab917ca9 Mon Sep 17 00:00:00 2001 From: Kaosiso Ezealigo Date: Tue, 7 Jul 2026 11:33:34 +0200 Subject: [PATCH 3/4] Reverse course: adopt AGENTA_API_URL as primary, AGENTA_HOST as legacy fallback My previous commit claimed AGENTA_HOST was correct and AGENTA_API_URL was an internal-only override. That was wrong, confirmed by direct correction from jp plus a closer re-read of sdks/python/agenta/sdk/utils/init.py:87-102: the SDK actually checks AGENTA_API_INTERNAL_URL then AGENTA_API_URL FIRST, and only derives from AGENTA_HOST as a fallback when neither is set. I had conflated AGENTA_API_INTERNAL_URL (genuinely internal-only) with AGENTA_API_URL (the public API URL, confirmed by jp's own examples: https://eu.cloud.agenta.ai/api, http://localhost/api). lib.sh now accepts AGENTA_API_URL (already includes /api) as the primary variable, matching the SDK's own precedence, and falls back to deriving it from AGENTA_HOST (a bare host, legacy) only when AGENTA_API_URL is not set. Normalizes either input down to a bare-host internal AGENTA_HOST so every other script's existing /api/... and /services/... path literals stay unchanged - this is a config-parsing change in lib.sh only, not a rewrite of every script's call sites. Verified the derivation logic locally across all four cases (AGENTA_API_URL set, AGENTA_HOST-only legacy fallback, neither set defaulting to cloud, both set with AGENTA_API_URL correctly winning). Could not verify live against bighetzner this round: the instance is unreachable from this environment right now (DNS resolves, but the connection times out completely, even for a bare GET to /) while general internet access is otherwise fine (confirmed against cloud.agenta.ai) - flagged for a live check once reachable. --- skills/build-agent/SKILL.md | 48 +++++++++++++++---------------- skills/build-agent/scripts/lib.sh | 27 +++++++++++------ 2 files changed, 42 insertions(+), 33 deletions(-) diff --git a/skills/build-agent/SKILL.md b/skills/build-agent/SKILL.md index c89cd6b..b82062c 100644 --- a/skills/build-agent/SKILL.md +++ b/skills/build-agent/SKILL.md @@ -28,34 +28,33 @@ fallback; prefer what is written here. Do these two things once, before any build. -**1. Credentials.** The scripts need `AGENTA_API_KEY`, and `AGENTA_HOST` only if the user -self-hosts (it defaults to Agenta cloud, `https://cloud.agenta.ai`). - -`AGENTA_HOST` is the right variable here, not `AGENTA_API_URL`. These scripts call the -public REST API directly from outside Agenta's own infrastructure (your machine, CI, and so -on) the same way the Agenta SDK derives its own API URL: host + `/api`. `AGENTA_API_URL` is a -different, internal override the SDK uses when a workflow it runs *inside* Agenta's -infrastructure needs to reach the API at a different address than the public host (for -example, docker-internal networking on a self-hosted install) — it does not apply to a caller -hitting the public REST API from outside, which is all this skill ever does. Do not swap -`AGENTA_HOST` for `AGENTA_API_URL` here. +**1. Credentials.** The scripts need `AGENTA_API_KEY`, and `AGENTA_API_URL` only if the user +self-hosts or is on a non-default cloud region (it defaults to `https://cloud.agenta.ai/api`). + +`AGENTA_API_URL` is the right variable, not `AGENTA_HOST`. It is the full API URL, already +including `/api` (e.g. `https://eu.cloud.agenta.ai/api`, or `http://localhost/api` for a +local self-hosted install) — this matches how the Agenta SDK itself resolves the backend: +`AGENTA_API_URL` takes priority whenever it is set. `AGENTA_HOST` (a bare host, no `/api` +suffix) is only a legacy fallback the SDK derives an API URL from when `AGENTA_API_URL` is +not set — prefer `AGENTA_API_URL` for anything new. - Ask the user for their API key. Point them to it: the **API keys** page in their Agenta - project settings (on cloud, under `https://cloud.agenta.ai`). Ask for the host URL only if - they self-host, in which case it is their own Agenta domain. + project settings (on cloud, under `https://cloud.agenta.ai`). Ask for the API URL only if + they self-host or use a non-default cloud region, in which case it is their own Agenta + domain plus `/api`. - Then offer to set it up for them, either way they prefer: - **Write it for them:** create a `.env` file in the working directory with - `AGENTA_API_KEY=...` (and `AGENTA_HOST=...` if self-hosting). `lib.sh` picks up a local - `.env` automatically. + `AGENTA_API_KEY=...` (and `AGENTA_API_URL=https://your-domain/api` if self-hosting). + `lib.sh` picks up a local `.env` automatically. - **Hand them a block to paste:** give them the lines to `export`, or the `.env` contents to create themselves. - Never print or commit the key. Add `.env` to `.gitignore` if the directory is a repo. - **`https://cloud.agenta.ai` above is a one-time example for INITIAL setup only.** If a later runtime error tells you to add a credential to the project vault (or anything else - that means "go to your Agenta project"), point the user at their actual configured - `$AGENTA_HOST` — read it from the environment/`.env`, don't repeat the cloud URL from this - section by habit. A self-hosted user sent to `cloud.agenta.ai` for a vault that lives on - their own domain will not find what you told them to look for. + that means "go to your Agenta project"), point the user at their actual configured API + host — read it from `AGENTA_API_URL`/`.env`, don't repeat the cloud URL from this section + by habit. A self-hosted user sent to `cloud.agenta.ai` for a vault that lives on their own + domain will not find what you told them to look for. **2. Prerequisites.** Run `bash scripts/check-prereqs.sh`. It verifies `bash`, `curl`, and `jq` are installed. On a miss it prints the exact install command for the user's platform; @@ -195,11 +194,12 @@ Keep to the loop above for a simple agent. Read one of these only when the task - **Crons are UTC, five fields, one-minute floor.** Convert the user's local time yourself. - **needs_auth means stop.** If a needed connection is not `ready`, stop and ask the user to connect it. That is the whole job for that step. -- **Remediation guidance always uses the user's actual `$AGENTA_HOST`, never a hardcoded - cloud URL.** The `https://cloud.agenta.ai` example in the credentials section above is for - *initial* setup only. If a later runtime failure calls for telling the user to go add - something in their Agenta project (a vault key, a setting), point them at their actual - configured host — a self-hosted user sent to the cloud URL will look in the wrong place. +- **Remediation guidance always uses the user's actual configured API host, never a + hardcoded cloud URL.** The `https://cloud.agenta.ai` example in the credentials section + above is for *initial* setup only. If a later runtime failure calls for telling the user to + go add something in their Agenta project (a vault key, a setting), point them at their + actual `AGENTA_API_URL` (or `AGENTA_HOST` under the legacy fallback) — a self-hosted user + sent to the cloud URL will look in the wrong place. - **Discovery is a search, not an oracle.** `discover-tools.sh` / `discover-triggers.sh` return high-recall best guesses over the live catalog. The matched **connection state** is reliable; the matched **integration and action** are not always right. A search matches on words: "save diff --git a/skills/build-agent/scripts/lib.sh b/skills/build-agent/scripts/lib.sh index 1083213..1ee8ba5 100755 --- a/skills/build-agent/scripts/lib.sh +++ b/skills/build-agent/scripts/lib.sh @@ -5,12 +5,12 @@ # # Credentials (set by you before running any script): # AGENTA_API_KEY required. From your Agenta project settings (API keys). -# AGENTA_HOST optional. Defaults to Agenta cloud. Set it only if self-hosting. -# -# AGENTA_HOST, not AGENTA_API_URL: these scripts curl the public REST API directly from -# outside Agenta's infra, the same way the SDK derives its own api_url (host + "/api"). -# AGENTA_API_URL is a different, internal override for a workflow running INSIDE Agenta's -# infra that needs a different internal address than the public host. Not relevant here. +# AGENTA_API_URL optional. The full API URL, e.g. https://eu.cloud.agenta.ai/api or +# http://localhost/api. Set it if self-hosting or on a non-default cloud +# region. Defaults to https://cloud.agenta.ai/api. +# AGENTA_HOST optional, legacy fallback. A bare host (no /api suffix), e.g. +# https://your-domain. Only used to derive the API URL when +# AGENTA_API_URL is not set. Prefer AGENTA_API_URL. # # Precedence: values already in the environment win. If AGENTA_API_KEY is not in the # environment, the kit falls back to a .env file (AGENTA_ENV_FILE, then ./.env, then a @@ -29,14 +29,23 @@ if [ -z "${AGENTA_API_KEY:-}" ]; then done fi -# Cloud is the default. Self-hosted users set AGENTA_HOST to their own domain. -: "${AGENTA_HOST:=https://cloud.agenta.ai}" +# AGENTA_API_URL is the preferred variable and already includes /api (e.g. +# https://eu.cloud.agenta.ai/api). AGENTA_HOST is a legacy fallback, a bare host with no +# /api suffix, only consulted when AGENTA_API_URL is not set. Every call site below still +# builds its own /api/... or /services/... path, so normalize either input down to a bare +# host in AGENTA_HOST for internal use — that keeps every other script in this kit unchanged. +if [ -n "${AGENTA_API_URL:-}" ]; then + AGENTA_HOST="${AGENTA_API_URL%/}" + AGENTA_HOST="${AGENTA_HOST%/api}" +else + : "${AGENTA_HOST:=https://cloud.agenta.ai}" +fi if [ -z "${AGENTA_API_KEY:-}" ]; then { echo "AGENTA_API_KEY is not set." echo "Get a key from your Agenta project settings (API keys page), then set it one of two ways:" - echo " export AGENTA_API_KEY=... # and AGENTA_HOST=https://your-domain if self-hosting" + echo " export AGENTA_API_KEY=... # and AGENTA_API_URL=https://your-domain/api if self-hosting" echo " echo 'AGENTA_API_KEY=...' > .env # a .env in this directory is picked up automatically" } >&2 exit 1 From cd8f5ee4dc5bf19aa61006e1c64c9e3785664e35 Mon Sep 17 00:00:00 2001 From: Kaosiso Ezealigo Date: Tue, 7 Jul 2026 13:23:28 +0200 Subject: [PATCH 4/4] Wipe AGENTA_HOST entirely, AGENTA_API_URL only Per jp: this skill hasn't shipped to any real users yet, so there is no back-compat burden to preserve. Removed AGENTA_HOST entirely instead of keeping it as a legacy fallback. lib.sh now only reads AGENTA_API_URL (defaults to https://cloud.agenta.ai/api), derives an internal bare-root variable for the one call site that needs a non-/api path (test-agent.sh's /services/agent/v0/invoke), and every other script's /api/... path literals are untouched. No AGENTA_HOST references remain anywhere in the skill. Verified end to end against bighetzner: build.sh (create + invoke) succeeds with only AGENTA_API_URL set, RESOLVED prints correctly, throwaway agent archived afterward. Also updated the two local .env files in ~/Desktop/agenta-skill-test that still had AGENTA_HOST. --- skills/build-agent/SKILL.md | 11 ++++------ skills/build-agent/scripts/lib.sh | 26 ++++++++---------------- skills/build-agent/scripts/test-agent.sh | 2 +- 3 files changed, 14 insertions(+), 25 deletions(-) diff --git a/skills/build-agent/SKILL.md b/skills/build-agent/SKILL.md index b82062c..8872080 100644 --- a/skills/build-agent/SKILL.md +++ b/skills/build-agent/SKILL.md @@ -31,12 +31,9 @@ Do these two things once, before any build. **1. Credentials.** The scripts need `AGENTA_API_KEY`, and `AGENTA_API_URL` only if the user self-hosts or is on a non-default cloud region (it defaults to `https://cloud.agenta.ai/api`). -`AGENTA_API_URL` is the right variable, not `AGENTA_HOST`. It is the full API URL, already -including `/api` (e.g. `https://eu.cloud.agenta.ai/api`, or `http://localhost/api` for a -local self-hosted install) — this matches how the Agenta SDK itself resolves the backend: -`AGENTA_API_URL` takes priority whenever it is set. `AGENTA_HOST` (a bare host, no `/api` -suffix) is only a legacy fallback the SDK derives an API URL from when `AGENTA_API_URL` is -not set — prefer `AGENTA_API_URL` for anything new. +`AGENTA_API_URL` is the full API URL, already including `/api` (e.g. +`https://eu.cloud.agenta.ai/api`, or `http://localhost/api` for a local self-hosted install) +— this matches how the Agenta SDK itself resolves the backend. - Ask the user for their API key. Point them to it: the **API keys** page in their Agenta project settings (on cloud, under `https://cloud.agenta.ai`). Ask for the API URL only if @@ -198,7 +195,7 @@ Keep to the loop above for a simple agent. Read one of these only when the task hardcoded cloud URL.** The `https://cloud.agenta.ai` example in the credentials section above is for *initial* setup only. If a later runtime failure calls for telling the user to go add something in their Agenta project (a vault key, a setting), point them at their - actual `AGENTA_API_URL` (or `AGENTA_HOST` under the legacy fallback) — a self-hosted user + actual `AGENTA_API_URL` — a self-hosted user sent to the cloud URL will look in the wrong place. - **Discovery is a search, not an oracle.** `discover-tools.sh` / `discover-triggers.sh` return high-recall best guesses over the live catalog. The matched **connection state** is reliable; diff --git a/skills/build-agent/scripts/lib.sh b/skills/build-agent/scripts/lib.sh index 1ee8ba5..b2a8a82 100755 --- a/skills/build-agent/scripts/lib.sh +++ b/skills/build-agent/scripts/lib.sh @@ -8,9 +8,6 @@ # AGENTA_API_URL optional. The full API URL, e.g. https://eu.cloud.agenta.ai/api or # http://localhost/api. Set it if self-hosting or on a non-default cloud # region. Defaults to https://cloud.agenta.ai/api. -# AGENTA_HOST optional, legacy fallback. A bare host (no /api suffix), e.g. -# https://your-domain. Only used to derive the API URL when -# AGENTA_API_URL is not set. Prefer AGENTA_API_URL. # # Precedence: values already in the environment win. If AGENTA_API_KEY is not in the # environment, the kit falls back to a .env file (AGENTA_ENV_FILE, then ./.env, then a @@ -29,17 +26,12 @@ if [ -z "${AGENTA_API_KEY:-}" ]; then done fi -# AGENTA_API_URL is the preferred variable and already includes /api (e.g. -# https://eu.cloud.agenta.ai/api). AGENTA_HOST is a legacy fallback, a bare host with no -# /api suffix, only consulted when AGENTA_API_URL is not set. Every call site below still -# builds its own /api/... or /services/... path, so normalize either input down to a bare -# host in AGENTA_HOST for internal use — that keeps every other script in this kit unchanged. -if [ -n "${AGENTA_API_URL:-}" ]; then - AGENTA_HOST="${AGENTA_API_URL%/}" - AGENTA_HOST="${AGENTA_HOST%/api}" -else - : "${AGENTA_HOST:=https://cloud.agenta.ai}" -fi +# Cloud is the default. AGENTA_API_URL already includes /api (e.g. https://eu.cloud.agenta.ai/api). +: "${AGENTA_API_URL:=https://cloud.agenta.ai/api}" +_API_BASE="${AGENTA_API_URL%/}" +# Every call site below builds its own /api/... or /services/... path, so also keep a bare +# root (no /api suffix) for the one call site that needs a non-/api path. +_API_ROOT="${_API_BASE%/api}" if [ -z "${AGENTA_API_KEY:-}" ]; then { @@ -53,9 +45,9 @@ fi _AUTH=(-H "Authorization: ApiKey $AGENTA_API_KEY" -H "Content-Type: application/json") -agenta_post() { curl -s -X POST "$AGENTA_HOST$1" "${_AUTH[@]}" -d "$2"; } -agenta_get() { curl -s "$AGENTA_HOST$1" "${_AUTH[@]}"; } -agenta_delete() { curl -s -X DELETE "$AGENTA_HOST$1" "${_AUTH[@]}"; } +agenta_post() { curl -s -X POST "$_API_ROOT$1" "${_AUTH[@]}" -d "$2"; } +agenta_get() { curl -s "$_API_ROOT$1" "${_AUTH[@]}"; } +agenta_delete() { curl -s -X DELETE "$_API_ROOT$1" "${_AUTH[@]}"; } # Resolves a argument for create-schedule.sh / create-subscription.sh. # A real revision id (from create-agent.sh / build.sh / update-agent.sh) passes straight diff --git a/skills/build-agent/scripts/test-agent.sh b/skills/build-agent/scripts/test-agent.sh index 3ad203f..0098863 100755 --- a/skills/build-agent/scripts/test-agent.sh +++ b/skills/build-agent/scripts/test-agent.sh @@ -53,7 +53,7 @@ RESP_FILE="$TMP/resp.json"; HDR="$TMP/headers" # Accept: application/json negotiates the non-streaming (batch) invoke — one JSON object back, # not an event stream. -curl -s -X POST "$AGENTA_HOST/services/agent/v0/invoke" \ +curl -s -X POST "$_API_ROOT/services/agent/v0/invoke" \ -H "Authorization: ApiKey $AGENTA_API_KEY" -H "Content-Type: application/json" \ -H "Accept: application/json" \ --max-time 600 -D "$HDR" -d "$BODY" > "$RESP_FILE"